CircleCI environment variables

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=foo
    	echo $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 $BAR
	environment:
    	FOO: foo
    	BAR: 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.01
    	environment:
        	FOO: foo
    	steps:
        	- 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.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

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

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