Secrets and Env Vars

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.

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.

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.)

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

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

• Using Env Vars in the value of an Env Var
• Increasing the size limit of Env Vars
• Exposing Env Vars and using them in another Step

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.

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.

   

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.

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.

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].

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:

• A central vault or database - such as HashiCorp or Doppler - to store the Secrets. It must be accessible via a CLI.
• A Script Step to access the central vault/database, pull the Secret and set it to sensitive on Bitrise.

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.

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:

• Export them from the Vault instance.
• Iterate over them and mark both of them as sensitive.

You can use this Script to achieve both:

# Exporting the Secrets
vault kv get --format=json secret/hello | jq -r '.data.data | 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
done

Check out Env Vars and Secrets in action

Go to your app