Secrets and Env Vars

Published at 2021-09-29

Every secret Environment Variable (Env Var) is an Env Var but not every Env Var is a secret Env Var!

About Env Vars

In your Workflow Editor, you can set an Env Var with a key and a value in the Env Vars tab which is a collection of all the Env Vars registered for your app. Env vars can be referenced as many times as you wish in any of your Workflow Steps, unless you set them for a specific Workflow.

Check out our short YouTube tutorial on how to insert variables in Step inputs!

If you click the insert variable button next to any Step input field in your Workflow, you can select the suitable Env Var from the Insert variable pop-up window. This interactive list displays all the available Env Vars you have set in the Env Vars tab and those that have been already generated by previous Steps in the Workflow.

For example, if you click into an input of the third Step of your Workflow, the Insert variable list will include all the Env Vars (outputs) generated by the first and second steps, and the ones you have registered in Env Vars. The list will not show those which will be generated by the fourth, fifth, sixth Steps.

You can also replace the variable for a new one in Env Vars. Delete the old value and set the new one. If you toggle the Replace variables in inputs to the right, the new value will be used everywhere in your Workflow.

Secrets and Env Vars

Protect your secrets

Contrary to secret Env Vars, Env Vars are fully exposed in builds triggered by pull requests so you should not add any sensitive information to Env Vars.

Setting an Env Var in Workflows

Under App Environmental Variables, you can set all the Env Vars you wish to use later on in all your Workflows.

Custom Env Vars

When you start a build manually, you can set custom Environment Variables in the advanced options. However, be aware that if they have the same key as an App Env Var, the latter takes precedence! That is, if they have the same key but different values, the build will use the value of the App Env Var.

You can set Env Vars for any of your Workflows separately as well. If you wish to set an Env Var with a variable which will be only used in a particular Workflow, then select the respective Workflow from the list and add the Env Var there. The list is comprised of the Workflows you named for your app. (In this example below, the app has a deploy, primary and dummy Workflow.)

Secrets and Env Vars

Check out our list of Available Environment Variables exposed by Bitrise CLI and

Read about some useful tricks you can do with Environment Variables:

About Secrets

Secret Env Vars are special type of Env Vars as they hide information in an encrypted format so that your private input is not exposed in the build logs/bitrise.yml. Secret Env Vars can be set by adding the Env Var key and the variable in the Secrets tab of the Workflow Editor.

.yml size limitations

Please note that the total, combined size of the bitrise.yml and the bitrise.secrets.yml file cannot exceed 200KB.

Adding a secret Env Var

You can add a secret Env Var to your Workflow using our Secrets tab.

  1. Click Add new on the Secrets tab.
  2. Set the key and value fields.

    Secrets and Env Vars

You can also add a secret Env Var directly in a Step’s SENSITIVE input.

Editing a secret Env Var

Once you’ve added a new secret Env Var in the Secrets tab, you come back to it any time, modify its content or make it protected from curious eyes!

  1. Click Edit next to the value of your secret Env Var.
  2. Modify its content if needed.
  3. If you want to hide the value, click Make it protected. A lock is shown.
  4. Delete the secret Env Var if you do not need it any more. Please note if you hit this button, the whole row will get deleted.

Life after Make it protected

Please note if you clicked this button, neither you nor anybody with the access to the app can unlock or check the value again.

Since this change is irreversible, a confirmation pop-up window will be displayed prior to saving your changes.

You can show and hide the value of an Env Var with the eye icon. This feature is useful if you have a long list of secret env vars in Secrets and you wish to check the value of only one secret env var while leaving the other values hidden. If a value is hidden, it’s represented with the crossed out eye icon.

Secrets and Env Vars

If you toggle the Replace variables in inputs to the right, the new value will be used everywhere in your Workflow.

If builds triggered by Pull Requests need to access Secrets’ values, then toggle the Expose for Pull Request to the right. This will make Secrets’ values available for the build machines. In build logs, however, none of your Secrets’ values will be available but printed as [REDACTED].

About SENSITIVE label

In the case of public apps, Step input fields containing sensitive information are marked with a SENSITIVE label and only secret Env Vars can be used there! The Expose for Pull Request toggle is by default disabled and cannot be enabled.

Head over to Secrets for more information on secret filtering.

Managing Secrets from a central location

By default, all Secrets are handled on the app level. You can reuse Secret keys across multiple Bitrise apps, even if their corresponding values are different for each app.

However, it is possible to set up a Secret that holds the same value for all your apps, and manage that Secret from one location. For example, if all your apps need access to the same API, it makes sense to store the Secret containing the API key in a central location. If the API key ever changes, you only need to change it in that single location and the change applies to all your Bitrise apps.

Setting up such a Secret (or multiple Secrets) requires two things:

To create a new Secret and store it in a central location during a build:

  1. Add a Script Step to ALL Workflows where you want to use the Secrets.
  2. Add the necessary commands to access your vault and pull the Secrets. The exact commands depend on the service you’re using.
  3. Use the envman tool to mark the Secrets as sensitive. The envman tool has the following syntax:
    envman add --key KEY --value value --sensitive .
  4. Make sure the Step doesn’t display the value of the Secret in the build log. To do so, remove set -x from the Step’s content.

Secret filtering

Please note that if you have secret filtering turned off, your Secrets will not be filtered and thus their value can still be visible in logs.

For example, let’s say you have a HashiCorp Vault instance called secret/hello. You have two Secrets in this vault instance: foo with the value world and foo2 with the value world2. To use these Secrets in a Bitrise build, you need to:

You can use this Script to achieve both:

# Exporting the Secrets
vault kv get --format=json secret/hello | jq -r ' | to_entries[] | [.key, .value] | @tsv' | 
# Iterating over the Secrets and marking them as sensitive
while IFS=$'\t' read -r key value; do
    envman add --key "$key" --value "$value" --sensitive