Environment Variables
When the agent invokes your build scripts it passes in a set of standard Buildkite environment variables, along with any that you've defined in your build configuration. You can use these environment variables in your build steps and agent hooks.
On this page:
Standard Buildkite environment variables
The following environment variables are automatically provided to every job, and are read only. They can’t be overridden by your pipeline configuration or environment hooks.
BUILDKITE |
Always "true". |
|---|---|
BUILDKITE_AGENT_NAME |
Name of the agent running the job. Example: |
BUILDKITE_ARTIFACT_PATHS |
The artifact paths to upload after the job, if any have been specified. Example: |
BUILDKITE_BRANCH |
The branch being built. Example: |
BUILDKITE_BUILD_CHECKOUT_PATH |
The path where the agent has checked out your code for this build. Example: |
BUILDKITE_BUILD_CREATOR |
The name of the user who created the build. Example: |
BUILDKITE_BUILD_CREATOR_EMAIL |
The notification email of the user who created the build. Example: |
BUILDKITE_BUILD_CREATOR_TEAMS |
A colon separated list of non-private team names that the build creator belongs to. Example: |
BUILDKITE_BUILD_ID |
The UUID of the build. Example: |
BUILDKITE_BUILD_NUMBER |
The build number. This number increases by 1 with every build, and is guaranteed to be unique within each pipeline. Example: |
BUILDKITE_BUILD_URL |
The url for this build on Buildkite. Example: |
BUILDKITE_CLEAN_CHECKOUT |
Whether the build should perform a clean checkout. Example: |
BUILDKITE_COMMAND |
The command that will be run for the job. Example: |
BUILDKITE_COMMIT |
The commit of the build. Example: |
BUILDKITE_DISABLE_GIT_SUBMODULES |
When set to true prevents fetching of any git submodules during checkout. This variable is used by the buildkite-agent bootstrap script. Example: |
BUILDKITE_JOB_ID |
Internal UUID Buildkite uses for this job. Example: |
BUILDKITE_LABEL |
The label/name of the current job. Example: |
BUILDKITE_MESSAGE |
The message associated with the build, usually the commit message. Example: |
BUILDKITE_NO_LOCAL_HOOKS |
Whether local hooks in the repository are allowed. Example: |
BUILDKITE_ORGANIZATION_SLUG |
The organization name on Buildkite as used in URLs. Example: |
BUILDKITE_PIPELINE_DEFAULT_BRANCH |
The default branch for this pipeline. Example: |
BUILDKITE_PIPELINE_PROVIDER |
The ID of the source code provider for the pipeline’s repository. Example: |
BUILDKITE_PIPELINE_SLUG |
The pipeline slug on Buildkite as used in URLs. Example: |
BUILDKITE_PULL_REQUEST |
The number of the pull request if this branch is a pull request. Example: |
BUILDKITE_PULL_REQUEST_BASE_BRANCH |
The base branch that the pull request is targeting. Example: |
BUILDKITE_PULL_REQUEST_REPO |
The repository URL of the pull request. Example: |
BUILDKITE_REBUILT_FROM_BUILD_ID |
The UUID of the original build this was rebuilt from. Example: |
BUILDKITE_REBUILT_FROM_BUILD_NUMBER |
The UUID of the original build this was rebuilt from. Example: |
BUILDKITE_REPO |
The repository of your pipeline. Example: |
BUILDKITE_REFSPEC |
A custom refspec for the buildkite-agent bootstrap script to use when checking out code. Example: |
BUILDKITE_SOURCE |
The source of the event that created the build. Example: |
BUILDKITE_TAG |
The name of the tag being built, if this build was triggered from a tag. Example: |
BUILDKITE_TIMEOUT |
The number of minutes until Buildkite automatically cancels this job, if a timeout has been specified. Example: |
BUILDKITE_TRIGGERED_FROM_BUILD_ID |
The UUID of the build that triggered this build. Example: |
BUILDKITE_UNBLOCKER |
The name of the user who unblocked the build. Example: |
BUILDKITE_UNBLOCKER_UUID |
The UUID of the user who unblocked the build. Example: |
BUILDKITE_UNBLOCKER_TEAMS |
A colon separated list of non-private team names that the unblocker belongs to. Example: |
CI |
Always "true". |
Defining your own
You can define environment variables in your jobs in a few ways, depending on the nature of the value being set:
- Pipeline settings — for values that are not secret.
- Build pipeline configuration — for values that are not secret.
- An
environmentorpre-commandagent hook — for values that are secret or agent-specific.
Environment variable precedence
You can set environment variables in lots of different places, and which ones take precedence can get a little confusing. There are many different levels at which environment variables are merged together. The following walkthrough and examples demonstrate the order in which variables are combined, as if you had set variables in every available place.
When a job runs on an agent, the first combination of environment variables happens in the job itself:
Job environment
When a job runs on an agent, the first combination of environment variables happens in the job environment itself. This is the environment you can see in a job’s Environment tab in the Buildkite dashboard, and the one returned by the REST and GraphQL APIs.
The job environment is made by merging the following sets of values, in order:
| Standard | The set of variables provided by Buildkite to every job |
|---|---|
| Build | Optional variables set by you on the build when creating a new build in the UI or via the REST API |
| Step | Optional variables set by you on a step in the UI or in a pipeline.yml file |
| Pipeline | Optional variables set by you on a pipeline on the Pipeline Settings page |
For example, if had configured the following environment variables:
| Build | MY_ENV1="a" |
|---|---|
| Step | MY_ENV1="b" |
| Pipeline | MY_ENV1="c" |
In the final job environment, the value of MY_ENV would be "c".
Setting variables in a pipeline.yml
There are two places in a pipeline.yml file that you can set environment variables:
- In the
envattribute of command and trigger steps. - At the top of the yaml file, before you define your pipeline's steps.
Defining an environment variable at the top of your yaml file will set that variable on each of the command steps in the pipeline, and is equivalent to setting the env attribute on every step.
Top level pipeline environment variables will override what is set in the env attribute of an individual step.
Setting variables in a Trigger step
Environment variables are not automatically passed through to builds created with trigger steps. To set build-level environment variables on triggered builds, set the trigger step’s env attribute.
Agent environment
Separate to the job's base environment, your buildkite-agent process has an environment of its own. This is made up of:
- operating system environment variables
- any variables you set on your agent when you started it
- any environment variables that were inherited from how you started the process (i.e. systemd sets some env vars for you)
For a list of variables and configuration flags you can set on your agent, see the Buildkite Agent’s start command documentation.
Job runtime environment
Once the job is accepted by an agent, more environment merging happens. Starting with the environment that we put together in the Job Environment section, we merge in some of the variables from the agent environment.
Not all variables from the agent are available in the job runtime. For example, we remove the agent’s registration token and replace it with a build session token that has limited permissions. This new session token is used when you run the artifact, meta-data and pipeline commands inside the job.
After the agent variables have been merged, the bootstrap script is run.
The bootstrap runs any local and global hooks that have been defined on the agent machine, and any hooks provided by plugins. Variables that are set in these hooks will be merged into the runtime environment, and will override any previous values that are set.
Take care with environment variables in hooks
Variables that are defined in hooks can override anything that exists in the environment.
This is the environment your command runs in 🎉
Finally, if your job’s commands make any changes to the environment, those changes will only survive as long as the script is running.