Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Set an environment variable

2 months ago3 min read
Cloud
Server 3.x
Server 4.x
On This Page

There are several ways to use environment variables in CircleCI to provide variety in scope and authorization level.

Set an environment variable in a shell command

While CircleCI does not support interpolation when setting environment variables, it is possible to set variables for the current shell by using BASH_ENV. This is useful for both modifying your PATH and setting environment variables that reference other variables.

version: 2.1

jobs:
  build:
    docker:
      - image: smaant/lein-flyway:2.7.1-4.0.3
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Update PATH and Define Environment Variable at Runtime
          # Add source command to execute code and make variables
          # available in current step.
          command: |
            echo 'export PATH=/path/to/foo/bin:"$PATH"' >> "$BASH_ENV"
            echo 'export VERY_IMPORTANT=$(cat important_value)' >> "$BASH_ENV"
            source "$BASH_ENV"

For more information, refer to your shell’s documentation on setting environment variables.

Set an environment variable in a step

To set an environment variable in a step, use the environment key.

version: 2.1

jobs:
  build:
    docker:
      - image: smaant/lein-flyway:2.7.1-4.0.3
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run:
          name: Run migrations
          command: sql/docker-entrypoint.sh sql
          # Environment variable for a single command shell
          environment:
            DATABASE_URL: postgres://conductor:@localhost:5432/conductor_test

Set an environment variable in a job

To set an environment variable in a job, use the environment key.

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:2022.04-20.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    environment:
      FOO: bar

Set an environment variable in a context

  1. On the CircleCI web app, go to Organization Settings.

    Contexts
  2. Select the context you want to associate your environment variable with, or create a new one by clicking the Create Context button.

  3. Click Add Environment Variable and enter a name and value.

  4. Use your new environment variable in your .circleci/config.yml once the context is added under the workflows key, as follows:

    version: 2.1
    
    workflows:
      test-env-vars:
        jobs:
          - build:
              context: my_context_name # has an env var called MY_ENV_VAR
    
    jobs:
      build:
        docker:
          - image: cimg/base:2021.11
            auth:
              username: mydockerhub-user
              password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        steps:
          - checkout
          - run:
              name: "echo an env var that is part of our context"
              command: |
                echo $MY_ENV_VAR

Creating a context allows you to share environment variables across multiple projects, and control who has access. For more information about controlling access to env vars with contexts, refer to the Restricting a context documentation.

Set an environment variable in a project

  1. On the CircleCI web app, go to your project’s settings. You can do this two ways: Navigate to Projects on the side navigation, and then click the ellipsis button in the project’s row, or click the Project Settings button on the project’s individual Pipelines page.

    Environment Variables
  2. Click on Environment Variables in the side navigation.

  3. Click the Add Variable button to enter a name and value of the new environment variable.

  4. Use your new environment variables in your .circleci/config.yml as follows:

    version: 2.1
    
    workflows:
      test-env-vars:
        jobs:
          - build
    
    jobs:
      build:
        docker:
          - image: cimg/base:2021.11
            auth:
              username: mydockerhub-user
              password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        steps:
          - checkout
          - run:
              name: "echo an env var that is part of our project"
              command: |
                echo $MY_ENV_VAR # this env var must be set within the project

Once created, environment variables are hidden and uneditable in the application. Changing an environment variable is only possible by deleting and recreating it.

Set an environment variable in a container

Environment variables can also be set for a Docker container. To do this, use the environment key.

version: 2.1

jobs:
  build:
    docker:
      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        # environment variables available for entrypoint/command run by docker container
        environment:
          MY_ENV_VAR_1: my-value-1
          MY_ENV_VAR_2: my-value-2

The following example shows separate environment variable settings for the primary container image (listed first) and the secondary or service container image.

version: 2.1

jobs:
  build:
    docker:
      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          MY_ENV_VAR_1: my-value-1
          MY_ENV_VAR_2: my-value-2
      - image: <image>:<tag>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          MY_ENV_VAR_3: my-value-3
          MY_ENV_VAR_4: my-value-4

Encoding multi-line environment variables

If you are having difficulty adding a multiline environment variable, use base64 to encode it.

$ echo "foobar" | base64 --wrap=0
Zm9vYmFyCg==

Store the resulting value in a CircleCI environment variable.

$ echo $MYVAR
Zm9vYmFyCg==

Decode the variable in any commands that use the variable.

$ echo $MYVAR | base64 --decode | docker login -u my_docker_user --password-stdin
Login Succeeded

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.