Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Introduction to environment variables

1 month ago4 min read
Cloud
Server v4.x
Server v3.x
Server v2.x
Helpful Resources
On This Page

Introduction

Use environment variables to set up various configuration options, and keep your set-up secure with secrets, private keys, and contexts. Environment variables in CircleCI are governed by an order of precedence, allowing control at each level in your configuration.

If you have existing environment variables (or contexts) and you would like to rename your organization or repository, please follow the Rename organizations and repositories guide to make sure you do not lose access to environment variables or contexts in the process.

Built-in environment variables

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

For a full list of built-in environment variables, see the Project values and variables page.

Private keys and secrets

To add private keys or secrets as environment variables for use throughout your project, navigate to Project Settings > Environment Variables in the CircleCI web app. You can find step-by-step instructions of this process on the Environment variables page. The variable values 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.

Private environment variables enable you to store secrets safely, even when your project is public. Refer to the Building open source projects page for associated security and settings information.

Secrets masking

Secrets masking is not available on version 2.x of self-hosted installations of CircleCI server.

Environment variables and contexts may hold project secrets or keys that perform crucial functions for your applications. Secrets masking provides added security within CircleCI by obscuring environment variables in the job output when echo or print is used.

Secrets masking is applied to environment variables set within Project Settings or Contexts in the web app.

The value of the environment variable or context 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

Environment variable usage options

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.

Order of precedence

Environment variables are used according to a specific precedence order, as follows:

  1. Environment variables declared inside a shell command in a run step, for example FOO=bar make install.
  2. Environment variables declared with the environment key for a run step.
  3. Environment variables set with the environment key for a job.
  4. Special CircleCI environment variables defined in the CircleCI Built-in environment variables document.
  5. Context environment variables (assuming the user has access to the context). See the Contexts documentation for more information.
  6. Project-level environment variables set on the Project Settings page in the web app.

Environment variables declared inside a shell command run step, for example FOO=bar make install, will override environment variables declared with the environment and contexts keys. Environment variables added on the Contexts page in the web app will take precedence over variables added on the Project Settings page.

Environment variable order of precedence

Example configuration of environment variables

Consider the example .circleci/config.yml below:

version: 2.1

jobs: # basic units of work in a run
  build:
    docker: # use the Docker executor
      # CircleCI Node images available at: https://circleci.com/developer/images/image/cimg/node
      - image: cimg/node:18.11.0
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
    steps: # steps that comprise the `build` job
      - checkout # check out source code to working directory
      # Run a step to setup an environment variable
      # Redirect MY_ENV_VAR into $BASH_ENV
      - run:
          name: "Setup custom environment variables"
          command: echo 'export MY_ENV_VAR="FOO"' >> "$BASH_ENV"
      - run: # print the name of the branch we're on
          name: "What branch am I on?"
          command: echo ${CIRCLE_BRANCH}
      # Run another step, the same as above; note that you can
      # invoke environment variable without curly braces.
      - run:
          name: "What branch am I on now?"
          command: echo $CIRCLE_BRANCH
      - run:
          name: "What was my custom environment variable?"
          command: echo ${MY_ENV_VAR}
      - run:
          name: "Print an env var stored in the Project"
          command: echo ${PROJECT_ENV_VAR}
      - run:
          name: "Print an env var stored in a Context"
          command: echo ${CONTEXT_ENV_VAR}

workflows: # a single workflow with a single job called build
  build:
    jobs:
      - build:
          context: Testing-Env-Vars

The above .circleci/config.yml demonstrates the following:

  • Setting custom environment variables
  • Reading a built-in environment variable that CircleCI provides (CIRCLE_BRANCH)
  • How variables are used (or interpolated) in your .circleci/config.yml
  • Secrets masking, applied to environment variable set in the project or within a context.

When the above configuration runs, the output looks like the below image. Notice the environment variables stored in the project is masked, and displays as ****:

Environment variable interpolation example

Notice there are two similar steps in the above image and configuration - “What branch am I on?” These steps illustrate two different methods to read environment variables.

In the example configuration above, two syntaxes are used: ${VAR} and $VAR. Both syntaxes are supported. You can read more about shell parameter expansion in the Bash documentation.

Parameters and bash environment

In general, CircleCI does not support interpolating environment variables in the configuration. Values used are treated as literals. This can cause issues when defining working_directory, modifying PATH, and sharing variables across multiple run steps.

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

working_directory: /go/src/github.com/$ORGNAME/$REPONAME

You can reuse pieces of configuration across your .circleci/config.yml file. By using the parameters declaration, you can pass values into reusable commands, jobs, and executors:

version: 2.1 # version 2.1 is required for reusing configuration

jobs:
  build:
    parameters:
      org_name:
        type: string
        default: my_org
      repo_name:
        type: string
        default: my_repo
    docker:
      - image: cimg/go:1.17.3
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
    steps:
      - run: echo "project directory is go/src/github.com/<< parameters.org_name >>/<< parameters.repo_name >>"

workflows:
  my_workflow:
    jobs:
      - build:
          org_name: my_organization
          repo_name: project1

      - build:
          org_name: my_organization
          repo_name: project2

For more information, read the documentation on using the parameters declaration.

Another possible method to interpolate values into your configuration is to use a run step to export environment variables to BASH_ENV, as shown below.

steps:
  - run:
      name: Setup Environment Variables
      command: |
        echo 'export PATH="$GOPATH"/bin:"$PATH"' >> "$BASH_ENV"
        echo 'export GIT_SHA1="$CIRCLE_SHA1"' >> "$BASH_ENV"

In every step, CircleCI uses bash to source BASH_ENV. This means that BASH_ENV is automatically loaded and run, allowing you to use interpolation and share environment variables across run steps.

Alpine Linux

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

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

version: 2.1

jobs:
  build:
    shell: /bin/sh -leo pipefail
    environment:
      BASH_ENV: /etc/profile

Notes on security

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 on CircleCI. Store secrets or keys in project or context settings in the CircleCI web app. For more information, see the Encryption section of the security page.

Running scripts within configuration may expose secret environment variables. See the Using shell scripts page for best practices for secure scripts.

Contexts

You can further restrict access to environment variables using contexts. Contexts are set from the Organization Settings in the CircleCI web app.

See also


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.