Using Environment Variables

This document describes using environment variables in CircleCI in the following sections:

Adding Environment Variables in the App

To add keys or secret environment variables to your private project, use the Environment Variables page of the Build > Project > Settings in the CircleCI application. The value of the variables are neither readable nor editable in the app after they are set. To change the value of an environment variable, delete the current variable and add it again with the new value. It is possible to add individual variables or to import variables from another project.

Adding Global Environment Variables

To add global environment variables that may be shared across projects, use the Settings > Contexts page of the CircleCI application. See the Contexts documentation for instructions.

Adding Environment Variables in the config.yml File

Warning: Do not add keys or secrets to a public CircleCI project. Be careful that the output doesn’t appear in build logs and that the variables are set using the CircleCI application and not in the config.yml file.

To define environment variables in your configuration for a single command, use the environment key in your image section to set variables for all commands run in the container, or inside a run step to set variables for a single command shell as shown in the following example:

version: 2.0
      - image: smaant/lein-flyway:2.7.1-4.0.3
      - image: circleci/postgres:9.6
      # Environment variable for all commands executed in the primary container
          POSTGRES_USER: conductor
          POSTGRES_DB: conductor_test
      - checkout

      - run: lein javac

      - run: lein deps

      - run:
          name: Run migrations
          command: sql/ sql
          # Environment variable for a single command shell
            DATABASE_URL: postgres://conductor:@localhost:5432/conductor_test

The following example shows separate environment variable settings for the primary container image (listed first) and the secondary or service container image.

version: 2
      - image: circleci/python:3.6.2
       # Environment variable for all commands executed in the primary container
          FLASK_CONFIG: testing
          TEST_DATABASE_URL: postgresql://ubuntu@localhost/circle_test?sslmode=disable
      - image: circleci/postgres:9.6

See the Writing Jobs with Steps document for details of the specification for the environment key.

Interpolating Environment Variables to Set Other Environment Variables

If you need to interpolate other environment variables to set an environment variable, the only place to do this at the moment is in bash. CircleCI 2.0 automatically sets a $BASH_ENV variable to a random name in /tmp, and will source this file for each step. As an example, you could add an entry to the $PATH as follows:

      - run: echo 'export PATH=/foo/bin:$PATH' >> $BASH_ENV
      - run: some_program_in_foo_bin

Injecting Environment Variables with the API

Build parameters are environment variables, therefore their names have to meet the following restrictions:

  • They must contain only ASCII letters, digits and the underscore character.
  • They must not begin with a number.
  • They must contain at least one character.

Aside from the usual constraints for environment variables there are no restrictions on the values themselves and are treated as simple strings. The order that build parameters are loaded in is not guaranteed so avoid interpolating one build parameter into another. It is best practice to set build parameters as an unordered list of independent environment variables.

For example, when you pass the parameters:

  "build_parameters": {
    "foo": "bar",
    "baz": 5,
    "qux": {"quux": 1},
    "list": ["a", "list", "of", "strings"]

Your build will see the environment variables:

export foo="bar"
export baz="5"
export qux="{\"quux\": 1}"
export list="[\"a\", \"list\", \"of\", \"strings\"]"

Build parameters are exported as environment variables inside the build’s containers and can be used by scripts/programs and commands in circle.yml. The injected environment variables may be used to influence the steps that are run during the build.

You might want to inject environment variables with the build_parameters key to enable your functional tests to build against different targets on each run. For example, a run with a deploy step to a staging environment that requires functional testing against different hosts. It is possible to include build_parameters by sending a JSON body with Content-type: application/json as in the following example that uses bash and curl (though you may also use an HTTP library in your language of choice).

  "build_parameters": {
    "param1": "value1",
    "param2": 500

For example using curl

curl \
  --header "Content-Type: application/json" \
  --data '{"build_parameters": {"param1": "value1", "param2": 500}}' \
  --request POST \$CIRCLE_TOKEN

The build will see the environment variables:

export param1="value1"
export param2="500"

Start a run with the POST API call, see the new build section of the API documentation for details. A POST with an empty body will start a new run of the named branch.

CircleCI Environment Variable Descriptions

CircleCI exports the environment variables in this section during each build, which are useful for more complex testing or deployment. Ideally, you will not have code which behaves differently in CI. But for the cases when it is necessary, CircleCI sets two environment variables which you can test:





CircleCI uses Bash, which follows the POSIX naming convention for environment variables. Uppercase and lowercase letters, digits, and the underscore are allowed. With the added rule that the first character must be a letter.

Build Details

CircleCI publishes the details of the currently running build in this list of variables:


Represents whether the current environment is a CI environment.

Has a value of true on our platform.


Represents whether the current environment is a CircleCI environment.

Has a value of true on our platform.


The name of the Git branch currently being built.


An integer representing the number of total build instances.


An integer between 0 and (CIRCLECI_NODE_TOTAL - 1) representing a specific build instance.


The CircleCI build number.


The number of previous builds in the branch.


The URL for the current build.


The SHA1 hash for the current build’s last commit.


The GitHub/Bitbucket username of the user who triggered the build.


The current job’s name.


The working_directory for the current the job.


The GitHub/Bitbucket compare URL between commits in the build.


The GitHub/Bitbucket repository URL.

CIRCLE_PR_NUMBER (only available in forked PR builds)

The GitHub/Bitbucket pull request number.

CIRCLE_PR_REPONAME (only available in forked PR builds)

The GitHub/Bitbucket repository name in which the pull request was made.

CIRCLE_PR_USERNAME (only available in forked PR builds)

The GitHub/Bitbucket username of the user who created the pull request.


Comma-separated list of pull requests this build is a part of.


If this build is part of only one pull request, its URL will be populated here. If there was more than one pull request, it will contain one of the pull request URLs (picked randomly).


Same as CIRCLE_PULL_REQUESTS, only kept for the backward compatibility with 1.0.


Same as CIRCLE_PULL_REQUEST, only kept for the backward compatibility with 1.0.


The name of the git tag being tested, e.g. ‘release-v1.5.4’, if the build is running for a tag. See the CircleCI 1.0 documentation of tags for more information.


The username or organization name of the project being tested, i.e. “foo” in


The repository name of the project being tested, i.e. “bar” in


The directory where test timing data can be found.