Set an environment variable
On This Page
There are several ways to use environment variables in CircleCI to provide variety in scope and authorization level.
|Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls.|
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: cimg/base:2023.06 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=VALUE_CONTENT" >> "$BASH_ENV" source "$BASH_ENV"
| Depending on your shell, you may have to append the new variable to a shell startup file like |
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
version: 2.1 jobs: build: docker: - image: cimg/base:2023.06 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
version: 2.1 jobs: build: docker: - image: cimg/base:2022.04-20.04 environment: FOO: bar
|Integers longer than 6 digits will be converted to an exponential number. To avoid this, store them as a string instead (i.e. "1234567").|
Set an environment variable in a context
On the CircleCI web app, go to Organization Settings.
Select the context you want to associate your environment variable with, or create a new one by clicking the Create Context button.
Click Add Environment Variable and enter a name and value.
Use your new environment variable in your
.circleci/config.ymlonce 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:2023.06 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
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.
Click on Environment Variables in the side navigation.
Click the Add Variable button to enter a name and value of the new environment variable.
Use your new environment variables in your
version: 2.1 workflows: test-env-vars: jobs: - build jobs: build: docker: - image: cimg/base:2023.06 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 variables set in this way are not available to steps run within the container, they are only available to the entrypoint/command run by the container. By default, CircleCI will ignore the entrypoint for a job’s primary container. For the primary container’s environment variables to be useful, you will need to preserve the entrypoint. For more information, see the Adding an entrypoint section of the Custom images guide.|
version: 2.1 jobs: build: docker: - image: cimg/base:2023.06 # 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.
|While hard-coded environment variable values will be passed on correctly to the secondary or service container, contexts or project specific environment variables will not be interpolated for non-primary containers.|
version: 2.1 jobs: build: docker: - image: cimg/base:2023.06 environment: MY_ENV_VAR_1: my-value-1 MY_ENV_VAR_2: my-value-2 - image: cimg/postgres:15.3.0 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
| Not all command-line programs take credentials in the same way that |
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.