Introduction to environment variables – CircleCI

Use environment variables to configure various configuration settings and keep your configuration secure with secrets, private keys, and contexts. Environment variables in CircleCI are governed by an order of precedence, allowing control at every level of your configuration. See the Set an Environment Variable page for guidance on the different ways to set an environment variable.

If you have existing environment variables (or contexts) and want to rename

your organization or repository, follow the Rename organizations and repositories guide to ensure that you don’t lose access to environment variables or contexts in the process.

All projects have access to CircleCI’s built-in environment variables. These environment variables have a scope at the job level, so they can be used with the context key in a job, but do not exist at a pipeline level.

For a complete list of built-in environment variables, see the Project Values and Variables page.

To add private keys or secrets as environment variables for use throughout the project, go to Project Settings > Environment Variables in the CircleCI web application. You can find step-by-step instructions for this process on the Environment Variables page. Variable values are not readable or editable in the application after you set them. To change the value of an environment variable, delete the current variable and add it back with the new value.

Private environment variables allow you to store secrets securely, even when your project is public. See the Creating Open Source Projects page for security and associated configuration information.

Secret masking is not available in version 2.x of self-hosted installations of the CircleCI server.

Environment variables and contexts can contain secrets or project keys that perform critical functions for your applications. Secret masking provides additional security within CircleCI by hiding environment variables in job output when using echo or print.

Secret masking applies to environment variables set in Project Settings or Contexts in the web application.

The value of the environment or context variable

will not be masked in the job output if:

the value of the environment variable

• is less than 4 characters The value

of the environment variable

• is equal to one of

true, true, false, or false

CircleCI uses Bash, which follows the POSIX naming convention for environment variables. Valid characters include letters (uppercase and lowercase), digits, and the underscore. The first character of each environment variable must be a letter.

Environment variables are used in a specific order of precedence, as follows:

Environment variables declared within a shell command in an execution step

1. , for example FOO=bar make install

. Environment variables declared with the environment key for an execution step. Environment variables

2. set with the environment key for a job

. Special CircleCI environment variables defined in the

3. CircleCI Built-in Environment Variables document.
5. Context environment variables (assuming the user has access to the context). See the context documentation for more information.
6. Project-level environment variables set on the Project Settings page of the Web application.

Environment variables

declared within an execution step shell command, for example FOO=bar make install, will override environment variables declared with environment and context keys. Environment variables added on the Contexts page of the Web application take precedence over variables added on the Project Settings page.

<img src="https://circleci.com/docs/assets/img/docs/env-var-order.png" alt="Environment variable priority order"

/> Consider the .circleci/config.yml example below: The .circleci/config.yml above shows the following: Configuring custom environment variables Reading a built-in environment variable provided by CircleCI (CIRCLE_BRANCH) How variables are used (or interpolated) in your .

circleci/config.yml

• Secret masking, applied to the environment variable set in the project or within a context.

When you run the above configuration, the output looks like the following image. Notice that the environment variables stored in the project are masked and displayed as ****

:

Notice that there are two similar steps in the image and settings above: “What branch am I on?” These steps illustrate two different methods for reading environment variables.

In the previous example configuration, two syntaxes are used: ${VAR} and $VAR. Both syntaxes are supported. You can learn more about expanding shell parameters in the Bash documentation.

In general, CircleCI does not support interpolation of environment variables in configuration. The values used are treated as literals. This can cause problems when defining working_directory, modifying PATH, and sharing variables in various execution steps.

In the following example, $ORGNAME and $REPONAME will not be interpolated.

You can reuse configuration parts in your .circleci/config.yml file. Using parameter declaration, you can pass values to reusable commands, jobs, and executors:

For more information, read the documentation on using parameter declaration

.

Another possible method for interpolating values in settings is to use an execution step to export variables from environment to BASH_ENV, as shown below.

At each step, CircleCI uses bash to get BASH_ENV. This means that BASH_ENV loads and runs automatically, allowing you to use interpolation and share environment variables between execution steps.

An image that has been based on Alpine Linux (such as Docker), uses the ash shell.

To use environment variables with bash, add the shell and environment keys to your job.

Do not add secrets or keys inside the .circleci/config.yml file. The full text of .circleci/config.yml is visible to developers with access to your project in CircleCI. Store secrets or keys in the project or context settings in the CircleCI web application. For more information, see the Encryption section of the security page.

Running scripts within the configuration can expose secret environment variables. See the Using Shell Scripts page for best practices for safe scripts.

You can further restrict access to environment variables by using contexts. Contexts are set from the organization settings in the CircleCI web application.

• Security recommendations
• Set an environment variable
• Inject variables using the CircleCI API