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.

Standard Buildkite environment variables

The following environment variables are automatically provided to every job, and are read only. They can’t be overriden by your pipeline configuration or environment hooks.

BUILDKITE Always "true".
BUILDKITE_AGENT_NAME Name of the agent running the job.

Example: "my-agent-1"

BUILDKITE_ARTIFACT_PATHS The artifact paths to upload after the job, if any have been specified.

Example: "tmp/capybara/**/*;coverage/**/*"

BUILDKITE_BRANCH The branch being built.

Example: "master"

BUILDKITE_BUILD_CHECKOUT_PATH The path where the agent has checked out your code for this build.

Example: "/var/lib/buildkite-agent/builds/agent-1/pipeline-2"

BUILDKITE_BUILD_CREATOR The name of the user who created the build.

Example: "Tracy Tester"

BUILDKITE_BUILD_CREATOR_EMAIL The notification email of the user who created the build.

Example: "tracy@acme-inc.com"

BUILDKITE_BUILD_CREATOR_TEAMS A colon separated list of team names that the build creator belongs to.

Example: "everyone:platform"


Example: "4735ba57-80d0-46e2-8fa0-b28223a86586", or "" if not a rebuild.

BUILDKITE_BUILD_NUMBER The build number. This number increases by 1 with every build, and is guaranteed to be unique within each pipeline.

Example: "1514"

BUILDKITE_BUILD_URL The url for this build on Buildkite.

Example: "https://buildkite.com/acme-inc/my-project/builds/1514"

BUILDKITE_CLEAN_CHECKOUT Whether the build should perform a clean checkout.

Example: "true" or "false"

BUILDKITE_COMMAND The command that will be run for the job.

Example: "script/buildkite/specs"

BUILDKITE_COMMIT The commit of the build.

Example: "83a20ec058e2fb00e7fa4558c4c6e81e2dcf253d"

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: "true"

BUILDKITE_JOB_ID Internal UUID Buildkite uses for this job.

Example: "e44f9784-e20e-4b93-a21d-f41fd5869db9"

BUILDKITE_LABEL The label/name of the current job.

Example: ":hammer: Specs"

BUILDKITE_MESSAGE The message associated with the build, usually the commit message.

Example: "Added a great new feature"

BUILDKITE_NO_LOCAL_HOOKS Whether local hooks in the repository are allowed.

Example: "true" or "false"

BUILDKITE_ORGANIZATION_SLUG The organization name on Buildkite as used in URLs.

Example: "acme-inc"

BUILDKITE_PIPELINE_DEFAULT_BRANCH The default branch for this pipeline.

Example: "master"

BUILDKITE_PIPELINE_PROVIDER The ID of the source code provider for the pipeline’s repository.

Example: "github"

BUILDKITE_PIPELINE_SLUG The pipeline slug on Buildkite as used in URLs.

Example: "my-project"

BUILDKITE_PULL_REQUEST The number of the pull request if this branch is a pull request.

Example: "123" for pull request #123, or "false" if not a pull request.

BUILDKITE_PULL_REQUEST_BASE_BRANCH The base branch that the pull request is targetting.

Example: "master", or "" if not a pull request.

BUILDKITE_PULL_REQUEST_REPO The repository URL of the pull request.

Example: "git://github.com/acme-inc/my-project.git", or "" if not a pull request.

BUILDKITE_REBUILT_FROM_BUILD_ID The UUID of the original build this was rebuilt from.

Example: "4735ba57-80d0-46e2-8fa0-b28223a86586", or "" if not a rebuild.

BUILDKITE_REBUILT_FROM_BUILD_NUMBER The UUID of the original build this was rebuilt from.

Example: "1514", or "" if not a rebuild.

BUILDKITE_REPO The repository of your pipeline.

Example: "git@github.com:acme-inc/my-project.git"

BUILDKITE_REFSPEC A custom refspec for the `buildkite-agent` bootstrap script to use when checking out code.

Example: "+refs/weird/123abc:refs/local/weird/456"

BUILDKITE_SOURCE The source of the event that created the build.

Example: "webhook", "api", "ui", "trigger_job", or "schedule"

BUILDKITE_TAG The name of the tag being built, if this build was triggered from a tag.

Example: "v1.2.3"

BUILDKITE_TIMEOUT The number of minutes until Buildkite automatically cancels this job, if a timeout has been specified.

Example: "15" for 15 minutes, or "false" if no timeout is set

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 environment or pre-command agent 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

This is a base environment, and is created fresh for every job. This is also the environment that is returned if you look at a job using the REST API or the Environment tab in Buildkite.

The job environment is made up of at least the standard set, and up to three additional sets of variables combined together:

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

These four sets of variables are merged together in the following order of precedence: Standard environment set > Build > Step > Pipeline

Setting variables in a pipeline.yml

There are two places in a pipeline.yml file that you can set environment variables:

  1. In the env attribute of command and trigger steps.
  2. 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. This will override what is set in the env attribute of an individual step.

Setting variables in a Trigger step

Environment variables set in the env attribute of a trigger step end up as build-level environment variables on the newly created build.

If you're using a 3.x agent, you can use variable interpolation to set variables for a trigger step that are already set elsewhere in the parent build. For example:

- FOO=bar
- trigger: some-pipeline
    - FOO=$FOO # triggered build will have `FOO=bar`

Environment variables set at top of a pipeline.yaml aren't applied to trigger steps

The only variables that are passed through to a trigger step's build are those you set in that 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/flags you can set on your agent, see the buildkite-agent start page. For a deeper look at what's involved in starting the agent, you can see the the buildkite-agent start code on github.

Job accepted by an agent

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 of the variables from the agent are added, and some variables are created fresh at this point. For example, we don't add the agent's registration token, we instead create a new access token for this specific job.

At this point we add the following:

  • variables that describe the agent that the job is running on
  • variables to tell the bootstrap and other commands what to do

After the agent variables have been merged, the bootstrap script is run. It adds its own variables to the environment, and runs any local and global hooks that have been defined on the agent machine (e.g. plugin, environment etc.) This causes any variables that are set in hooks to be merged in to the environment.

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, any changes that you make to the environment from within the job script will only survive as long as the script is running.