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"

BUILDKITE_BUILD_ID The UUID of the build.

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

BUILDKITE_TRIGGERED_FROM_BUILD_ID The UUID of the build that triggered this build.

Example: "5aa7c894-c8c0-435b-bc17-13923b90f163", or "" if the build was not triggered from another build.

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

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:

  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.

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.