Environment Variables

An Environment Variable (Env Var) is a key-value pair that holds data that you can use in your builds by inserting them into Step inputs. For example, working directory of an app's repository is often stored in an Env Var so you don't have to specify the path for every Step input that needs it.

You can configure Env Vars for an entire app or for specific Workflows. App level Env Vars are available for every Workflow of the app; Workflow level Env Vars are only available for the given Workflow.

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.

Protect confidential information

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

Availability order of Environment Variables

Environment Variables (Env Var) are available after the Env Var is processed.

There are Env Vars exposed by the Bitrise CLI. These are available from the start: for example, BITRISE_SOURCE_DIR and BITRISE_TRIGGERED_WORKFLOW_ID.

All other Env Vars are processed and made available as the build progresses.

The processing order is the following:

  1. Env Vars exposed by the Bitrise CLI.

  2. Secrets: they are processed before a Workflow starts.

  3. One-off Environment Variables specified for the build through our API.

  4. App Environment Variables.

  5. Workflow Environment Variables: when the processing of the specified Workflow starts, the Env Vars specified for that Workflow are made available.

    If the Workflow has Workflows chained before or after it, the Environment Variables of the chained workflows are processed and made available right before the first Step of the Workflow would run.

  6. Step inputs: they are exposed for each Step, right before the Step would start.

  7. Step outputs: they are exposed by the specific Step, so those are available for subsequent Steps after the Step finishes.

Setting an Env Var

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.

To set a new Environment Variable (Env Var):

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Go to the Env Vars tab.

  4. Choose the level of the Env Var.

    • Scroll down to the App Environment Variables section to set an app level Env Var.

      Secrets and Env Vars
    • Scroll down to one of the Workflow Environment Variables sections to set an Env Var for that specific Workflow.

      Secrets and Env Vars
  5. Click the Add new button in your chosen section.

  6. Type the Env Var key into the Key input field and the value into the Value input field.

    Replacing variables in inputs

    We don't recommend toggling on the Replace variables in inputs? option, 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.

  7. Click Save in the top right corner.

That's it. Your new Env Var is saved and ready to be used.

Setting a custom Env Var when starting a build

When scheduling a new build or starting a new build manually, you have the option to set up custom Environment Variables (Env Var). These variables are only available for the build you started or scheduled.

Don't use the same key as an App Env Var

App Environment Variables have precedence over custom Environment Variables! This means that if you define a custom Env Var with the same key as an App Env Var, the build will use the value of the App Env Var.

  1. Go to your Dashboard and select the app you need.

  2. Select Start/Schedule a Build.

    This opens the Build configuration pop-up window.

  3. In the Build configuration pop-up window, select the Advanced tab.

  4. Find the Custom Environment Variables section.

  5. Enter a key and a value.

    Replacing variables in inputs

    We don't recommend toggling on the Replace variables in inputs? option, 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.

  6. Press the + Add Environment Variable button.

  7. Finish starting or scheduling the build.

Using an Env Var in a Step input

Many Step inputs accept Environment Variables (Env Var) and Secrets as input values.

Sensitive inputs

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

To use an Env Var or a Secret as a Step input value:

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Select a Workflow from the WORKFLOW dropdown menu.

  4. Select a Step from the Workflow. For example, the Git Clone Repository Step.

  5. Choose a Step input. For example, the Clone destination (local) directory path input of the Git Clone Repository Step.

  6. Next to the name of the input, click Insert variable.

  7. Find the Env Var in the list, and select it.

    You can search for the Env Var by typing its key (or a part of it) into the Filter by key search field.

    Env Vars generated by Steps

    The interactive list of Env Vars will show the Env Vars that are generated by previous Steps of the Workflow. For example, if you want to insert an Env Var into one of the inputs of the third Step in the Workflow, you can choose from the Env Vars generated by the first and second Steps.

That's it. The next time you run a build of that Workflow, the Step input will use the value of the inserted Env Var as the Step input value.

Using Env Vars in the value of an Env Var

Environment Variables (Env Var) normally contain a simple string value. However, it is possible to set up an Env Var that includes other Env Vars as values.

Secrets as variable values

The methods described here also apply to Secrets. You can also embed a Secret within an Env Var.

You can, at any time, use another Environment Variable in the value of an Env Var - embedding the Env Var, so to speak. For example, let's say we want to set the value of the $BITRISE_AUTH Env Var to $PERSONAL_ACCESS_TOKEN which is another Env Var.

To do this, you need to make sure that the key of $BITRISE_AUTH is replaced with its value so that its the embedded Env Var that is passed on to the Workflows and Steps.

  1. Open your app on Bitrise.

  2. Go to the Workflow tab.

  3. Go to the Env Vars tab.

  4. Under the key of the Env Var you need, toggle the Replace variables in inputs? toggle to active.

Exposing Env Vars and using them in another Step or Workflow

You can expose Env Vars from one Step and make it available for every other Step performed after the Step during the build. You can use envman to manage Env Vars.

Important

This section requires familiarity with the structure and requirements of the bitrise.yml configuration file.

Here is a simple example where we're adding a new Env Var with the key MY_RELEASE_NOTE:

envman add --key MY_RELEASE_NOTE --value "This is the release note"

You can call envman in any Step, including a Script Step, or even in your own script (stored in your repository) if you call it from a bitrise build.

You can specify the value as the --value parameter, or by using pipe:

echo 'hi' | envman add --key MY_RELEASE_NOTE

You can also read the value from a file:

envman add --key MY_RELEASE_NOTE --valuefile ./some/file/path

Once the Env Var is exposed, you can use it like any other Env Var. You can use these exposed Env Vars in the inputs of other Steps as well.

Here is an example where we’re exposing the release note Env Var and then using it in another Script and in a Send a Slack message Step.

workflows:
  example:
    steps:
    - script:
        inputs:
        - content: |
            #!/bin/bash
            envman add --key MY_RELEASE_NOTE --value "This is the release note"
    - script:
        inputs:
        - content: |
            #!/bin/bash
            echo "My Release Note: $MY_RELEASE_NOTE"
    - slack:
        inputs:
        - channel: ...
        - webhook_url: ...
        - message: "Release Note: $MY_RELEASE_NOTE"

If you want to expose the value of an Env Var to be accessible through the key of another Env Var, you can do so.

For example, to expose the value of BITRISE_BUILD_NUMBER under the key MY_BUILD_NUMBER:

 envman add --key MY_BUILD_NUMBER --value "${BITRISE_BUILD_NUMBER}"

After this, subsequent Steps can get the value of BITRISE_BUILD_NUMBER from the MY_BUILD_NUMBER Env Var. If you change the value of BITRISE_BUILD_NUMBER after this, the value of MY_BUILD_NUMBER won’t be modified, it will still hold the original value!

If you need to know if a custom Env Var has been defined, you can easily check it, and even overwrite its value:

#!/bin/bash
set -ex
if [ ! -z "$API_PROJECT_SCHEME" ] ; then
  envman add --key PROJECT_SCHEME --value "$API_PROJECT_SCHEME"
fi

This script checks whether the API_PROJECT_SCHEME Env Var is defined, and if it is, its value will be assigned to the PROJECT_SCHEME Environment Variable, overwriting the original value of PROJECT_SCHEME.

Alternatively, you can set Env Vars for Workflows too. The Env Vars you set for a Workflow will overwrite the Env Var if defined as an app Env Var or a Secret.

Here is an example Workflow which defines an Env Var, and then runs another Workflow that can use those Env Vars:

workflows:

  deploy-alpha:
    envs:
    - ENV_TYPE: alpha
    after_run:
    - _deploy

  _deploy:
    steps:
    - script:
        inputs:
        - content: |
            #!/bin/bash
            echo "ENV_TYPE: $ENV_TYPE"

If you run the deploy-alpha Workflow, that will set the ENV_TYPE Env Var to alpha, then it will run the deploy Workflow, which can use that Env Var. In this example, it will simply print its value (the printed text will be: ENV_TYPE: alpha).