Environment Variables

Users can declare Environment Variables on three different levels:

In addition to the user-declared Env Vars, there are Env Vars automatically exposed by either the Bitrise CLI or bitrise.io. These are always available in any build. You can find the list of these here: Available Environment Variables

App level Env Vars are available to every build of a given app. Whenever you create a new Workflow, for example, it immediately and automatically has access to every single app level Env Var.

A Workflow level Env Var is only available to the specific Workflow it was defined in. If your primary Workflow has an Env Var with the key TEST_ENV, your deploy Workflow won't be able to access that Env Var.

A Step level Env Var is defined within a particular Step of a build. Such an Env Var is not available to other Workflows, or to the preceding Steps in the same Workflow. Subsequent Steps, however, can access it. Step outputs are also exposed as Environment Variables.

You can set Environment Variables, regardless of level, in both the Workflow Editor, in your app's bitrise.yml file, or during a build with a custom Script using the envman tool:

Environment Variables have a given processing order based on their level: 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:

To set a new Environment Variable (Env Var):

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

Replacing variables in inputs ensures that the value of the Env Var will be passed to the build instead of the key. For details, check Replacing variables in inputs.

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

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.

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

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

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.

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.

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.

You can set Env Vars during a build by defining them in a Step, typically a Script Step. To accomplish this, you can use the envman tool.

Here is a simple example where we're using envman to add 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 Step 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.

You can set Env Vars directly in the YAML configuration file for your app. You can set both app level and Workflow level Env Vars in your app's config file.

In this example, we have a configuration with an app-level Env Var called TEST_KEY:

app:  
  envs:  
  - opts:      
      is_expand: false    
    TEST_KEY: test value

In this example, the deploy-alpha Workflow defines an Env Var called ENV_TYPE, and then runs another Workflow that can use that Env Var:

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