CircleCI environment variables

Kenny DuMez
Kenny DuMez
Graphite software engineer

Developers are used to using environment variables to modify the behavior of programs or pass data to the programs without having to change the source code. CircleCI makes it possible to define and use environment variables to fine-tune how jobs are run. CircleCI provides two types of environment variables: built-in environment variables and custom environment variables.

CircleCI sets up a few environment variables by default. These built-in environment variables are scoped at the job level. Hence, they can be used inside jobs, but they don't exist at the pipeline level. A full list of built-in environment variables is available in the CircleCI docs.

It's possible to set up custom environment variables in CircleCI. CircleCI provides different methods to create custom environment variables, and if the same variable is set in two different ways, CircleCI resolves the conflict by following an order of precedence. Following are the different ways you can set up environment variables in CircleCI in the order of precedence:

Inside the shell command in a run step, you can declare an environment variable in the same way you declare an environment variable in a typical bash shell:

Terminal
- run:
name: "Env variable in shell command"
command: |
FOO=foo
echo $FOO

This way of defining environment variables has the highest precedence and overrides environment variables declared using the other methods that follow.

A run step can be accompanied by an environment key. With this key, you can set up one or more environment variables:

Terminal
- run:
name: "Env variable in environment key"
command: echo $FOO $BAR
environment:
FOO: foo
BAR: bar

Similar to the environment key in a run step, you can set up job-wide environment variables using the environment key at the job level:

Terminal
jobs:
env-var-job:
docker:
- image: cimg/base:2020.01
environment:
FOO: foo
steps:
- checkout
- run:
name: "Job wide env variable"
command: echo $FOO

Context in CircleCI is a secure mechanism for sharing environment variables and secrets across projects in an organization. You can create a new context by navigating to Organization Settings > Contexts and clicking on Create Context:

Creating a new context

You need to provide a name for the context:

The new context dialog

Once the context is created, you can click on Add Environment Variable to define a new environment variable:

Context page

Then provide a name and value for your environment variable:

Adding a new environment variable

You can now use this environment variable in a job by adding a context key to the job's entry in the workflows section:

Terminal
version: 2.1
workflows:
my-workflow:
jobs:
- env-in-context:
context:
- MyContext
jobs:
env-in-context:
docker:
- image: cimg/base:2020.01
steps:
- checkout
- run:
name: "echo environment variable from context"
command: echo $FOO

You can set environment variables per project from the Project Settings page. Navigate to Project Settings > Environment variables and click on Add Environment variable:

Adding project-wide environment variable

Provide a name and value for the environment variable and click on Add Environment variable:

New environment variable dialog

You can now use this environment variable for this project without any additional setup:

Terminal
version: 2.1
workflows:
my-workflow:
jobs:
- env-in-context:
context:
- SomeContext
jobs:
env-in-context:
docker:
- image: cimg/base:2020.01
steps:
- checkout
- run:
name: "echo environment variable from project settings"
command: echo $FOO

Note: The built-in environment variables are situated between environment variables declared in the environment key for a job and environment variables declared in contexts in terms of precedence.

Environment variables in CircleCI are similar to the typical bash variables, and you can access them in run steps using the same syntax, $VARIABLE_NAME or ${VARIABLE_NAME}:

Terminal
- run:
name: "Using env variable"
command: echo $FOO

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2