circleci.com Open in urlscan Pro
13.35.93.13 Public Scan

Back to summary

Submitted URL:
https://circleci.com/docs/2.0/env-vars/
Effective URL:
https://circleci.com/docs/env-vars/
Submission: On October 04 via api (October 4th 2024, 9:34:12 am UTC) from US — Scanned from US

Form analysis
1 forms found in the DOM

<form novalidate="" action="" role="search" class="css-cssveg" data-hs-cf-bound="true">
  <div class="css-409epr">
    <div size="24" color="currentColor" class="css-19wtgi5"><svg role="img" focusable="false" viewBox="0 0 24 24" aria-label="Search" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="css-bleycz">
        <path fill-rule="evenodd" clip-rule="evenodd"
          d="M14 9C14 11.7614 11.7614 14 9 14C6.23858 14 4 11.7614 4 9C4 6.23858 6.23858 4 9 4C11.7614 4 14 6.23858 14 9ZM13.1922 14.6064C12.0236 15.4816 10.5723 16 9 16C5.13401 16 2 12.866 2 9C2 5.13401 5.13401 2 9 2C12.866 2 16 5.13401 16 9C16 10.5723 15.4816 12.0236 14.6064 13.1922L21.7019 20.2877C22.0924 20.6782 22.0924 21.3114 21.7019 21.7019C21.3114 22.0924 20.6782 22.0924 20.2877 21.7019L13.1922 14.6064Z">
        </path>
      </svg></div>
  </div>
  <div data-testid="search-documentation-reset" class="css-xxqz7m">
    <div size="28" color="currentColor" class="css-1pgy7j"><svg role="img" focusable="false" viewBox="0 0 24 24" aria-label="Cancel" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="css-bleycz">
        <path
          d="M17.9865 7.45711C18.3771 7.06658 18.3771 6.43342 17.9865 6.04289C17.596 5.65237 16.9628 5.65237 16.5723 6.04289L12.0294 10.5858L7.48653 6.04289C7.096 5.65237 6.46284 5.65237 6.07231 6.04289C5.68179 6.43342 5.68179 7.06658 6.07231 7.45711L10.6152 12L6.07231 16.5429C5.68179 16.9334 5.68179 17.5666 6.07231 17.9571C6.46284 18.3476 7.096 18.3476 7.48653 17.9571L12.0294 13.4142L16.5723 17.9571C16.9628 18.3476 17.596 18.3476 17.9865 17.9571C18.377 17.5666 18.377 16.9334 17.9865 16.5429L13.4436 12L17.9865 7.45711Z">
        </path>
      </svg></div>
  </div><input type="text" placeholder="Search" data-testid="search-documentation-inputbox" class="css-1cvkw1b" value="">
</form>

Text Content

Docs

Start Building for Free

HomeDocsOrbsImages
CircleCI.comAcademyBlogCommunitySupport

* About CircleCI

* Getting started

* Reference

* Orchestrate and trigger

* Execute jobs on managed compute resources

* Execute jobs on self-hosted runners

* Test

* Deploy

* Release

* Optimize

* Project Insights

* Package and re-use config with orbs

* Manage roles and permissions

* Manage security and secrets

Security features
* How CircleCI handles security
* Intro to environment variables
* Using contexts
* IP ranges
* Audit logs

Security recommendations
* Security overview
* Protecting against supply chain attacks
* Secure secrets handling

How-to guides
* Set an environment variable
* Inject environment variables with the API
* Debug with SSH
* Rotate project SSH keys
* Stop building a project on CircleCI
* Rename organizations and repositories
* Manage config policies

* Integration

* Developer toolkit

* Server administration v4.6

* Server administration v4.5

* Server administration v4.4

* Server administration v4.3

* Server administration v4.2

* Server administration v4.1

* Plans and pricing

* Contributing to CircleCI docs

INTRODUCTION TO ENVIRONMENT VARIABLES

1+ year ago5 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

HELPFUL RESOURCES

Keep environment variables private
Troubleshoot environment variables settings
Insert files as environment variables

ON THIS PAGE

* Introduction
* Built-in environment variables
* Private keys and secrets
* Secrets masking
* Environment variable usage options
* Order of precedence
* Example configuration of environment variables
* Parameters and bash environment
* Environment variable substitution
* Usage
* Alpine Linux
* Notes on security
* Contexts
* See also

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

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

Secrets masking will only prevent values from appearing in your job output.
Invoking a bash shell with the -x or -o xtrace options may inadvertently log
unmasked secrets (please refer to Using shell scripts). If your secrets appear
elsewhere, such as test results or artifacts, they will not be masked.
Additionally, values are still accessible to users debugging builds with SSH.

The secrets masking feature exists as a preventative measure to catch
unintentional display of secrets at the output. Best practice is to avoid
printing secrets to the output. There are many ways that secrets masking could
be bypassed, either accidentally or maliciously. For example, any process that
reformats the output of a command or script could remove secrets masking.

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.

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
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 ****:

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

An exception to this rule is using project environment variables to pull private
images.

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

The $BASH_ENV workaround only works with bash, and has not been confirmed to
work with other shells.

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.

ENVIRONMENT VARIABLE SUBSTITUTION

The CircleCI CLI offers a wrapper around the envsubst tool, available both
locally as well as in all jobs running on CircleCI. envsubst is a command-line
utility used to replace environment variables in text strings.

CLI command:

circleci env subst

USAGE

The circleci env subst command can accept text input from stdin or as an
argument.

Within your repository create a file such as template.json, with value replaced
by environment variable strings

{
"foo": "$FOO",
"provider": "${PROVIDER}"
}

envsubst can convert all types of environment variable strings, including those
encased in curly braces ({}).

The config example below shows the corresponding environment variables as if
they were defined directly within a step in the config. However, we strongly
recommend creating the environment variables in the CircleCI app, either in
Project Settings or as a context.

version: 2.1
jobs:
process-template:
docker:
- image: cimg/base:current
steps:
- checkout
- run:
name: Process template file
environment:
# Environment variables would typically be served via a context
FOO: bar
PROVIDER: circleci
command: |
circleci env subst < template.json > deploy.json
cat deploy.json
workflows:
env-subst-workflow:
jobs:
- process-template

In this example, the < symbol is used to redirect the contents of the
template.json file as input to the env subst command, while the > symbol is used
to redirect the output of the env subst command to the deploy.json.

You could alternatively pass input to the circleci env subst command as an
argument: circleci env subst "hello \$WORLD"

Output:

{
"foo": "bar",
"provider": "circleci"
}

For instructions on installing the CircleCI CLI locally, read the Installing the
CircleCI local CLI guide.

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.

circleci.com Open in urlscan Pro 13.35.93.13 Public Scan

Form analysis 1 forms found in the DOM

Text Content

circleci.com Open in urlscan Pro
13.35.93.13 Public Scan

Form analysis
1 forms found in the DOM