Secrets
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
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.
You can create a Secret either on the Secrets page in the Workflow Editor or when modifying Step inputs.
Secrets page
Step inputs
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
On the left, select Secrets.
-
Under Project level Secrets, click the button.
-
Add a key and a value.
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 option unchecked. 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. -
Optionally, you can replace the key of your Secret with its value in inputs: check the Replace variables in inputs option.
-
Optionally, you can expose your Secret to pull requests by selecting the option.
In most cases, we strongly recommend not to expose Secrets.
-
Click .
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
Select a Workflow and find the Step you want to configure.
-
Find the sensitive input you wish to modify.
-
Click the $ sign and then click Create in the dialog.
-
In the Create variable dialog, specify a key and a value for your new Secret.
-
Optionally, you can replace the key of your Secret with its value in inputs by checking the option.
-
Click the 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!
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
On the left, select Secrets.
-
Click Edit next to the value of your Secret.
-
Modify its content as needed.
-
Click .
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.
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
On the left, select Secrets.
-
Click Edit next to the value of your Secret.
-
Check .
-
The dialog will warn that the process is irreversible. Click Save and protect.
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.
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
On the left, select Secrets.
-
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 across multiple apps
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.
There are two ways to achieve this:
-
Managing your Secrets from a Workspace. This is only available on Enterprise plans.
-
Managing secrets from a central location such as a vault or database and pulling it with a Step.
Managing Secrets on a Workspace level
On Enterprise plans, you can store Secrets on a Workspace level. This means that the same Secret is accessible to all apps owned by that Workspace. This means increased security: only Workspace Owners and Managers can access these Secrets.
Downgrading
If you downgrade from an Enterprise plan, Workspace Secrets will be converted to app level Secrets.
When passing Secrets to your build, app level Secrets take precedence over Workspace level Secrets in the availability order. This also means that if you have two Secrets with the same key, the app level Secret will be used during the build.
To add a new secret:
-
On the Bitrise main page, select Settings on the navigation menu on the left. It takes you to the Workspace settings page.
-
On the Workspace settings page, select Shared resources.
-
Click the button.
-
Add a key and a value.
-
Configure the usage details of the Secret:
-
Replace variables in inputs: This passes the value of the Secret as a string to the build. Use this for embedded Secrets or Environment Variables: when the value of your Secret is the key of another Secret or Environment Variable. For most use cases, you don't need this checked.
-
Expose for pull requests: Exposing a Secret to a PR means that the Secret is available to use in pull request builds. Depending on your repository's privacy settings, this is a potential security risk!
-
Protected: The value cannot be changed or viewed again. This setting is irreversible once saved.
-
-
When you're ready, click Done.
Managing Secrets from a central vault or database
Setting up Secrets in a central location 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
envmantool 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 -xfrom the Step’scontent.
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.
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.
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the button on the main page.
-
On the left, select Secrets.
-
Click Add new to register the
BITRISE_SECRET_FILTERINGsecret Environment Variable with false value. -
Click in the top right corner.