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.
Built-in 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.
Custom environment variables
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:
Environment variable declared in a shell command
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:
- run:name: "Env variable in shell command"command: |FOO=fooecho $FOO
This way of defining environment variables has the highest precedence and overrides environment variables declared using the other methods that follow.
Environment variable declared using the environment key in a run step
A run
step can be accompanied by an environment
key. With this key, you can set up one or more environment variables:
- run:name: "Env variable in environment key"command: echo $FOO $BARenvironment:FOO: fooBAR: bar
Environment variable declared using the environment key in a job
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:
jobs:env-var-job:docker:- image: cimg/base:2020.01environment:FOO: foosteps:- checkout- run:name: "Job wide env variable"command: echo $FOO
Environment variable set within a context under organization settings
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:
You need to provide a name for the context:
Once the context is created, you can click on Add Environment Variable to define a new environment variable:
Then provide a name and value for your 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:
version: 2.1workflows:my-workflow:jobs:- env-in-context:context:- MyContextjobs:env-in-context:docker:- image: cimg/base:2020.01steps:- checkout- run:name: "echo environment variable from context"command: echo $FOO
Environment variable set under project settings
You can set environment variables per project from the Project Settings page. Navigate to Project Settings > Environment variables and click on Add Environment variable:
Provide a name and value for the environment variable and click on Add Environment variable:
You can now use this environment variable for this project without any additional setup:
version: 2.1workflows:my-workflow:jobs:- env-in-context:context:- SomeContextjobs:env-in-context:docker:- image: cimg/base:2020.01steps:- 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.
Using an environment variable
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}
:
- run:name: "Using env variable"command: echo $FOO