Using CircleCI Environment Variables
We export a number of environment variables during each build, which you may find useful for more complex testing or deployment.
Basics
Ideally, you won’t have code which behaves differently in CI. But for the cases when it’s necessary, we set two environment variables which you can test:
CIRCLECI
true
CI
true
We use Bash, which follows the POSIX naming convention for environment variables. Basically, uppercase and lowercase letters, digits, and the underscore are allowed. With the added rule that the first character should be a letter. Variable names are case-sensitive.
Build Details
We publish the details of the currently running build in these variables:
CIRCLE_PROJECT_USERNAME
The username or organization name of the project being tested, i.e. “foo” in circleci.com/gh/foo/bar/123
CIRCLE_PROJECT_REPONAME
The repository name of the project being tested, i.e. “bar” in circleci.com/gh/foo/bar/123
CIRCLE_BRANCH
The name of the Git branch being tested, e.g. ‘master’, if the build is running for a branch.
CIRCLE_TAG
The name of the git tag being tested, e.g. ‘release-v1.5.4’, if the build is running for a tag.
CIRCLE_SHA1
The SHA1 of the commit being tested.
CIRCLE_REPOSITORY_URL
A link to the homepage for the current repository, for example, https://github.com/circleci/frontend
.
CIRCLE_COMPARE_URL
A link to GitHub’s comparison view for this push. Not present for builds that are triggered by GitHub pushes.
CIRCLE_BUILD_URL
A permanent link to the current build, for example, https://circleci.com/gh/circleci/frontend/933
.
CIRCLE_BUILD_NUM
The build number, same as in circleci.com/gh/foo/bar/123
CIRCLE_PREVIOUS_BUILD_NUM
The build number of the previous build, same as in circleci.com/gh/foo/bar/123
CI_PULL_REQUESTS
Comma-separated list of pull requests this build is a part of.
CI_PULL_REQUEST
If this build is part of only one pull request, its URL will be populated here. If there was more than one pull request, it will contain one of the pull request URLs (picked randomly).
CIRCLE_ARTIFACTS
The directory whose contents are automatically saved as build artifacts.
CIRCLE_USERNAME
The GitHub login of the user who either pushed the code to GitHub or triggered the build from the UI/API.
CIRCLE_TEST_REPORTS
The directory whose contents are automatically processed as JUnit test metadata.
Building pull requests that come from forks
When the build is a part of a pull request from a fork, these variables will be available:
CIRCLE_PR_USERNAME
The username of the owner of the fork.
CIRCLE_PR_REPONAME
The name of the repository the pull request was submitted from.
CIRCLE_PR_NUMBER
The number of the pull request this build forms part of.
Parallelism
These variables are available for manually setting up parallelism:
CIRCLE_NODE_TOTAL
The total number of nodes across which the current test is running.
CIRCLE_NODE_INDEX
The index (0-based) of the current node.
CIRCLE_BUILD_IMAGE
The build image this build runs on.
Other
There are quite a few other environment variables set. Here are some of the ones you might be looking for:
HOME
/home/ubuntu
DISPLAY
:99
LANG
en_US.UTF-8
PATH
Includes /home/ubuntu/bin
Set your own!
You can of course set your own environment variables, too!
The only gotcha is that each command runs in its own shell, so just adding an
export FOO=bar
command won’t work.
All commands and data on CircleCI’s VMs can be accessed by any of your colleagues—we run your arbitrary code, so it is not possible to secure. Take this into account before adding important credentials that some colleagues do not have access to. Similarly, if your CircleCI project is public, don’t put any sensitive information/credentials into CircleCI, as environment variables or otherwise.
Setting environment variables for all commands using circle.yml
You can set environment variables in your circle.yml
file, that
will be set for every command.
Setting environment variables for all commands without adding them to git
Occasionally, you’ll need to add an API key or some other secret as an environment variable. You might not want to add the value to your git history. Instead, you can add environment variables using the Project settings > Environment Variables page of your project.
It’s important to note that environment variables configured through
the UI are exported during the machine
section of the build. This
means you cannot read UI environment variables during the machine: pre
. Another note, the value of these variables won’t be readable in the UI after setting them nor can you edit it. If you need to change its value, you should delete the current variable and add it again with the new value.
Keeping encrypted environment variables in source code
If you prefer to keep your sensitive environment variables checked into git, but encrypted, you can follow the process outlined at circleci/encrypted-files.
Per-command environment variables
You can set environment variables per-command as well. You can use standard bash syntax in your commands:
RAILS_ENV=test bundle exec rake test
You can also use the environment modifier in your
circle.yml
file.
Note: We don’t parse any environment variables in the webhooks
section of circle.yml
.