Secrets

Abstract

Secrets are a specific type of Environment Variable: they aren't shown in the bitrise.yml and their value is not exposed in the build logs.

Secrets are a specific type of Environment Variable: they hide their information in an encrypted format and their value is not exposed in the build logs. They aren't shown in the bitrise.yml configuration either. You can store confidential information, such as passwords or API keys as Secrets.

Just like Environment Variables, Secrets can be used as the value of a Step input: Using an Env Var in a Step input

Sensitive inputs

Input fields marked as SENSITIVE only accept Secrets as their input. Generally, we do not recommend changing the value of these inputs.

Setting a Secret

Every Env Var value is a string

The value of an Environment Variable or Secret can only be a string. Even if you set a number (for example, 7), it will be passed on as a string.

Using the $ character

You can use the $ character in the value of an Env Var or Secret (for example, in a password) but in that case always leave the Replace variables in inputs? toggle inactive. If you replace the variable's key with its value in inputs, the Bitrise CLI will treat the value as another Env Var because of the $ character.

There are two ways of creating a new Secret in the graphical UI of the Workflow Editor. In the first procedure, we're using the Secrets tab.

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Go to the Secrets tab.
Click the Add new button.
Type the Env Var key into the Key input field and the value into the Value input field.

Exposing Secrets to pull requests

Under the value, you can see the Expose for Pull Requests? toggle. By default, Secrets aren't exposed to pull requests. We strongly recommend not exposing Secrets to pull requests in most cases.
Replacing variables in inputs

All Env Vars have the is_expand property. On the UI, this is represented by the Replace variables in inputs? toggle. We do NOT recommend enabling it, unless the value of your Env Var or Secret is another Env Var or Secret.

Toggling on this option ensures that instead of the key of the Env Var, the value of the Env Var will be passed to the build. Normally, this is not necessary.

Please note that if you add a new Environment Variable directly in the bitrise.yml file and do NOT set the is_expand property, the default value will be true. We recommend explicitly setting is_expand in this case:
```
envs:
  - opts:
      is_expand: false
      KEY: VALUE
```
On the right under the Secret, click the Save button.

The other method is to create the Secrets when modifying the Step input values. You can only do this when the Step input is marked as SENSITIVE. Sensitive inputs only accept Secrets so you can either choose an existing one from a list, or create a new one.

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Select a Workflow and find the Step you want to configure.
Find the sensitive input you wish to modify.
Click into the input field.
Under the Create New Secret Env Var label, specify a key and a value for your new Secret.

Exposing Secrets to pull requests

Under the value, you can see the Expose for Pull Requests? toggle. By default, Secrets aren't exposed to pull requests. We strongly recommend not exposing Secrets to pull requests in most cases.
Replacing variables in inputs

All Env Vars have the is_expand property. On the UI, this is represented by the Replace variables in inputs? toggle. We do NOT recommend enabling it, unless the value of your Env Var or Secret is another Env Var or Secret.

Toggling on this option ensures that instead of the key of the Env Var, the value of the Env Var will be passed to the build. Normally, this is not necessary.

Please note that if you add a new Environment Variable directly in the bitrise.yml file and do NOT set the is_expand property, the default value will be true. We recommend explicitly setting is_expand in this case:
```
envs:
  - opts:
      is_expand: false
      KEY: VALUE
```
Click the Add new button.

Editing an existing Secret

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!

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Go to the Secrets tab.
Click Edit next to the value of your Secret.
Modify its content as needed.
On the right under the Secret, click the Save button.

Protecting the value of a Secret

Normally, you can show and hide the value of a Secret by clicking 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 while leaving the other values hidden. If a value is hidden, it’s represented with the crossed out eye icon.

However, you can hide the value of a Secret permanently by making it protected. If you do so, no one, including yourself, will be able to change or even view the value again.

A Secret's protection can't be undone

Making a Secret protected is irreversible. If you ever need to change the value, you will have to delete the Secret and create a new one.

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Go to the Secrets tab.
Click Edit next to the value of your Secret.
Click Make it protected.
The pop-up window will warn that the process is irreversible. Click Make it protected.

That's it. You can no longer view the value of the Secret.

Exposing a Secret to pull requests

By default, pull requests do not have access to the values of Secrets. This means that if a pull request opened from a fork of a repository triggers a build, that build can't use the app's Secrets.

If you need to grant pull request builds access to a particular Secret, you can expose that Secret to pull requests. However, even when exposed, its value won't be visible in the logs: it will be displayed as [REDACTED].

Protected Secrets can't be exposed

Once a Secret has been made protected, you can't expose it to pull request builds.

Public apps

If your app is a public app, you can't expose the app's Secrets to pull requests builds.

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Go to the Secrets tab.
Click Edit next to the value of your Secret.
Toggle the Expose for Pull Requests? toggle.

Once the Secret is exposed, pull request builds can access it.

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:

Add the Secrets as a key-value pair to your vault or database where you want to store them.
Add a Script Step to ALL Workflows where you want to use the Secrets.
Add the necessary commands to access your vault and pull the Secrets. The exact commands depend on the service you’re using.
Use the envman tool to mark the Secrets as sensitive. The envman tool has the following syntax:

envman add --key KEY --value value --sensitive .
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 redaction

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

Example 1. Storing your Secrets in a HashiCorp Vault

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

Redacting Secrets

The Bitrise CLI automatically redacts your Secret Env Vars and prints [REDACTED] with newlines after the key so that the Secret Env Vars are NOT VISIBLE in the build log. This applies to both private and public apps.

You can turn this off at any time though if you need to have your Secrets visible in logs.

Warning

This is a potential security risk. We strongly recommend not to turn off Secret redaction.

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Go to the Secrets tab.
Click Add new to register the BITRISE_SECRET_FILTERING secret Environment Variable with false value.
Click Save in the top right corner.

In this section: