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 job lifecycle hooks.

For best practices and recommendations about using secrets in your environment variables, see the Managing Secrets guide.

Buildkite environment variables

The following environment variables may be visible in your commands, plugins, and hooks.

Unverified commits

Note that GitHub accepts unsigned commits, including information about the commit author and passes them along to webhooks, so you should not rely on these for authentication unless you are confident that all of your commits are trusted.

BUILDKITE # This value cannot be modified

Always true
BUILDKITE_AGENT_ACCESS_TOKEN # This value cannot be modified

The agent session token for the job. The variable is read by the agent artifact and meta-data commands.

Example:

83d544ccc223c157d2bf80d3f2a32982c32c3c0db8e3674820da5064783fb091
BUILDKITE_AGENT_DEBUG #
  • Possible values:
  • true
  • false
This value cannot be modified

The value of the debug agent configuration option.
BUILDKITE_AGENT_DISCONNECT_AFTER_JOB #
  • Possible values:
  • true
  • false
This value cannot be modified

The value of the disconnect-after-job agent configuration option.
BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT # This value cannot be modified

The value of the disconnect-after-idle-timeout agent configuration option.

Example:

10
BUILDKITE_AGENT_ENDPOINT #

Default: https://agent.buildkite.com/v3

This value cannot be modified

The value of the endpoint agent configuration option. This is set as an environment variable by the bootstrap and then read by most of the buildkite-agent commands.
BUILDKITE_AGENT_EXPERIMENT # This value cannot be modified

A list of the experimental agent features that are currently enabled. The value can be set using the --experiment flag on the buildkite-agent start command or in your agent configuration file.

Example:

experiment1,experiment2
BUILDKITE_AGENT_HEALTH_CHECK_ADDR # This value cannot be modified

The value of the health-check-addr agent configuration option.

Example:

localhost:8080
BUILDKITE_AGENT_ID # This value cannot be modified

The UUID of the agent.

Example:

1a222222-e999-3636-8ddd-802222222222
BUILDKITE_AGENT_META_DATA_* # This value cannot be modified

The value of each agent tag. The tag name is appended to the end of the variable name. They can be set using the --tags flag on the buildkite-agent start command, or in the agent configuration file. The Queue tag is specifically used for isolating jobs and agents, and appears as the BUILDKITE_AGENT_META_DATA_QUEUE environment variable.

Example:

"BUILDKITE_AGENT_META_DATA_TAGNAME=tagvalue", "BUILDKITE_AGENT_META_DATA_QUEUE=some-queue"
BUILDKITE_AGENT_NAME # This value cannot be modified

The name of the agent that ran the job.

Example:

elastic-builders-088264dc4f9
BUILDKITE_AGENT_PID # This value cannot be modified

The process ID of the agent.

Example:

6
BUILDKITE_ARTIFACT_PATHS # This value cannot be modified

The artifact paths to upload after the job, if any have been specified. The value can be modified by exporting the environment variable in the environment or pre-checkout hooks.

Example:

tmp/capybara/**/*;coverage/**/*
BUILDKITE_ARTIFACT_UPLOAD_DESTINATION #

The path where artifacts will be uploaded. This variable is read by the buildkite-agent artifact upload command, and during the artifact upload phase of command steps. It can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.

Example:

s3://name-of-your-s3-bucket/$BUILDKITE_PIPELINE_ID/$BUILDKITE_BUILD_ID/$BUILDKITE_JOB_ID
BUILDKITE_BIN_PATH # This value cannot be modified

The path to the directory containing the buildkite-agent binary.

Example:

/usr/local/bin
BUILDKITE_BRANCH # This value cannot be modified

The branch being built.

Example:

main
BUILDKITE_BUILD_CHECKOUT_PATH # This value cannot be modified

The path where the agent has checked out your code for this build. This variable is read by the bootstrap when the agent is started, and can only be set by exporting the environment variable in the environment or pre-checkout hooks.

Example:

/var/lib/buildkite-agent/builds/agent-1/pipeline-2
BUILDKITE_BUILD_AUTHOR # This value cannot be modified

The name of the user who authored the commit being built. May be unverified. This value can be blank in some situations, including builds manually triggered using API or Buildkite web interface.

Example:

Carol Danvers
BUILDKITE_BUILD_AUTHOR_EMAIL # This value cannot be modified

The notification email of the user who authored the commit being built. May be unverified. This value can be blank in some situations, including builds manually triggered using API or Buildkite web interface.

Example:

cdanvers@kree-net.com
BUILDKITE_BUILD_CREATOR # This value cannot be modified

The name of the user who created the build. May be unverified.

Example:

Carol Danvers
BUILDKITE_BUILD_CREATOR_EMAIL # This value cannot be modified

The notification email of the user who created the build.

Example:

cdanvers@kree-net.com
BUILDKITE_BUILD_CREATOR_TEAMS # This value cannot be modified

A colon separated list of unverified non-private team slugs that the build creator belongs to.

Example:

everyone:platform
BUILDKITE_BUILD_ID # This value cannot be modified

The UUID of the build.

Example:

4735ba57-80d0-46e2-8fa0-b28223a86586
BUILDKITE_BUILD_NUMBER # This value cannot be modified

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

Example:

1514
BUILDKITE_BUILD_PATH # This value cannot be modified

The value of the build-path agent configuration option.

Example:

/var/lib/buildkite-agent/builds/
BUILDKITE_BUILD_URL # This value cannot be modified

The url for this build on Buildkite.

Example:

https://buildkite.com/acme-inc/my-project/builds/1514
BUILDKITE_CANCEL_GRACE_PERIOD #

Default: 10

This value cannot be modified

The value of the cancel-grace-period agent configuration option in seconds.
BUILDKITE_CANCEL_SIGNAL #

Default: SIGTERM

The value of the cancel-signal agent configuration option. The value can be modified by exporting the environment variable in the environment or pre-checkout hooks.
BUILDKITE_CLEAN_CHECKOUT #
  • Possible values:
  • true
  • false
This value cannot be modified

Whether the build should perform a clean checkout. The variable is read during the default checkout phase of the bootstrap and can be overridden in environment or pre-checkout hooks.
BUILDKITE_COMMAND # This value cannot be modified

The command that will be run for the job.

Example:

script/buildkite/specs
BUILDKITE_COMMAND_EVAL #
  • Possible values:
  • true
  • false
This value cannot be modified

The opposite of the value of the no-command-eval agent configuration option.
BUILDKITE_COMMAND_EXIT_STATUS # This value cannot be modified

The exit code from the last command run in the command hook.

Example:

-1
BUILDKITE_COMMIT # This value cannot be modified

The git commit object of the build. This is usually a 40-byte hexadecimal SHA-1 hash, but can also be a symbolic name like HEAD.

Example:

83a20ec058e2fb00e7fa4558c4c6e81e2dcf253d
BUILDKITE_CONFIG_PATH #

Default: /buildkite/buildkite-agent.cfg

This value cannot be modified

The path to the agent config file.
BUILDKITE_ENV_FILE # This value cannot be modified

The path to the file containing the job's environment variables.

Example:

/tmp/job-env-36711a2a-711a-484e-b180-e1b3711a80cf51b18711a
BUILDKITE_GIT_CLEAN_FLAGS #

The value of the git-clean-flags agent configuration option. The value can be modified by exporting the environment variable in the environment or pre-checkout hooks.

Example:

-ffxdq
BUILDKITE_GIT_CLONE_FLAGS #

The value of the git-clone-flags agent configuration option. The value can be modified by exporting the environment variable in the environment or pre-checkout hooks.

Example:

-v
BUILDKITE_GIT_SUBMODULES #
  • Possible values:
  • true
  • false
This value cannot be modified

The opposite of the value of the no-git-submodules agent configuration option.
BUILDKITE_GITHUB_DEPLOYMENT_ID # This value cannot be modified

The GitHub deployment ID. Only available on builds triggered by a GitHub Deployment.

Example:

87972451
BUILDKITE_GITHUB_DEPLOYMENT_ENVIRONMENT # This value cannot be modified

The name of the GitHub deployment environment. Only available on builds triggered by a GitHub Deployment.

Example:

production
BUILDKITE_GITHUB_DEPLOYMENT_TASK # This value cannot be modified

The name of the GitHub deployment task. Only available on builds triggered by a GitHub Deployment.

Example:

deploy
BUILDKITE_GITHUB_DEPLOYMENT_PAYLOAD # This value cannot be modified

The GitHub deployment payload data as serialized JSON. Only available on builds triggered by a GitHub Deployment.

Example:

production
BUILDKITE_HOOKS_PATH # This value cannot be modified

The value of the hooks-path agent configuration option.

Example:

/etc/buildkite-agent/hooks/
BUILDKITE_IGNORED_ENV # This value cannot be modified

A list of environment variables that have been set in your pipeline that are protected and will be overridden, used internally to pass data from the bootstrap to the agent.

Example:

BUILDKITE_GIT_CLEAN_FLAGS
BUILDKITE_JOB_ID # This value cannot be modified

The internal UUID Buildkite uses for this job.

Example:

e44f9784-e20e-4b93-a21d-f41fd5869db9
BUILDKITE_LABEL # This value cannot be modified

The label/name of the current job.

Example:

"🔨 Specs"
BUILDKITE_LAST_HOOK_EXIT_STATUS # This value cannot be modified

The exit code of the last hook that ran, used internally by the hooks.

Example:

-1
BUILDKITE_LOCAL_HOOKS_ENABLED #
  • Possible values:
  • true
  • false
This value cannot be modified

The opposite of the value of the no-local-hooks agent configuration option.
BUILDKITE_MESSAGE # This value cannot be modified

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

Example:

Added a great new feature
BUILDKITE_ORGANIZATION_SLUG # This value cannot be modified

The organization name on Buildkite as used in URLs.

Example:

acme-inc
BUILDKITE_PARALLEL_JOB # This value cannot be modified

The index of each parallel job created from a parallel build step, starting from 0. For a build step with parallelism: 5, the value would be 0, 1, 2, 3, and 4 respectively.

Example:

0
BUILDKITE_PARALLEL_JOB_COUNT # This value cannot be modified

The total number of parallel jobs created from a parallel build step. For a build step with parallelism: 5, the value is 5.

Example:

5
BUILDKITE_PIPELINE_DEFAULT_BRANCH # This value cannot be modified

The default branch for this pipeline.

Example:

main
BUILDKITE_PIPELINE_NAME # This value cannot be modified

The displayed pipeline name on Buildkite.

Example:

my_project
BUILDKITE_PIPELINE_PROVIDER # This value cannot be modified

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

Example:

github
BUILDKITE_PIPELINE_SLUG # This value cannot be modified

The pipeline slug on Buildkite as used in URLs.

Example:

my-project
BUILDKITE_PLUGINS # This value cannot be modified

A JSON object containing a list plugins used in the step, and their configuration.

Example:

[{"github.com/buildkite-plugins/docker-buildkite-plugin#v3.7.0":{"image":"node:lts-alpine3.14"}}]
BUILDKITE_PLUGINS_ENABLED #
  • Possible values:
  • true
  • false
This value cannot be modified

The opposite of the value of the no-plugins agent configuration option.
BUILDKITE_PLUGINS_PATH # This value cannot be modified

The value of the plugins-path agent configuration option.

Example:

/etc/buildkite-agent/plugins/
BUILDKITE_PLUGIN_VALIDATION #

Default: false

This value cannot be modified

Whether to validate plugin configuration and requirements. The value can be modified by exporting the environment variable in the environment or pre-checkout hooks, or in a pipeline.yml file. It can also be enabled using the no-plugin-validation agent configuration option.
BUILDKITE_PULL_REQUEST # This value cannot be modified

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 # This value cannot be modified

The base branch that the pull request is targeting.

Example:

"main", or "" if not a pull request
BUILDKITE_PULL_REQUEST_REPO # This value cannot be modified

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 # This value cannot be modified

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 # This value cannot be modified

The UUID of the original build this was rebuilt from.

Example:

"1514", or "" if not a rebuild
BUILDKITE_REFSPEC # This value cannot be modified

A custom refspec for the buildkite-agent bootstrap script to use when checking out code. This variable can be modified by exporting the environment variable in the environment or pre-checkout hooks.

Example:

+refs/weird/123abc:refs/local/weird/456
BUILDKITE_REPO # This value cannot be modified

The repository of your pipeline. This variable can be set by exporting the environment variable in the environment or pre-checkout hooks.

Example:

git@github.com:acme-inc/my-project.git
BUILDKITE_REPO_MIRROR # This value cannot be modified

Only available if the experimental feature git-mirrors is enabled. The path to the shared git mirror.

Example:

/tmp/buildkite-git-mirrors
BUILDKITE_RETRY_COUNT # This value cannot be modified

How many times this job has been retried.

Example:

0
BUILDKITE_S3_ACCESS_KEY_ID # This value cannot be modified

The access key ID for your S3 IAM user, for use with private S3 buckets. The variable is read by the buildkite-agent artifact upload command, and during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.

Example:

AKIAIOSFODNN7EXAMPLE
BUILDKITE_S3_ACCESS_URL # This value cannot be modified

The access URL for your private S3 bucket, if you are using a proxy. The variable is read by the buildkite-agent artifact upload command, as well as during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.

Example:

https://buildkite-artifacts.example.com/
BUILDKITE_S3_ACL #

Default: public-read

  • Possible values:
  • private
  • public-read-write
  • public-read
  • authenticated-read
  • bucket-owner-read
  • bucket-owner-full-control
This value cannot be modified

The Access Control List to be set on artifacts being uploaded to your private S3 bucket. The variable is read by the buildkite-agent artifact upload command, as well as during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.

Must be one of the following values which map to S3 Canned ACL grants.
BUILDKITE_S3_DEFAULT_REGION #

Default: us-east-1

This value cannot be modified

The region of your private S3 bucket. The variable is read by the buildkite-agent artifact upload command, as well as during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.
BUILDKITE_S3_SECRET_ACCESS_KEY # This value cannot be modified

The secret access key for your S3 IAM user, for use with private S3 buckets. The variable is read by the buildkite-agent artifact upload command, as well as during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks. Do not print or export this variable anywhere except your agent hooks.

Example:

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
BUILDKITE_S3_SSE_ENABLED #

Default: false

This value cannot be modified

Whether to enable encryption for the artifacts in your private S3 bucket. The variable is read by the buildkite-agent artifact upload command, as well as during the artifact upload phase of command steps. The value can only be set by exporting the environment variable in the environment, pre-checkout or pre-command hooks.
BUILDKITE_SHELL # This value cannot be modified

The value of the shell agent configuration option.

Example:

"/bin/bash -e -c"
BUILDKITE_SOURCE #
  • Possible values:
  • webhook
  • api
  • ui
  • trigger_job
  • schedule
This value cannot be modified

The source of the event that created the build.
BUILDKITE_SSH_KEYSCAN #
  • Possible values:
  • true
  • false
This value cannot be modified

The opposite of the value of the no-ssh-keyscan agent configuration option.
BUILDKITE_STEP_ID # This value cannot be modified

A unique string that identifies a step.

Example:

080b7d73-986d-4a39-a510-b34f9faf4710
BUILDKITE_STEP_KEY # This value cannot be modified

The value of the key command step attribute, a unique string set by you to identify a step.

Example:

tests-06
BUILDKITE_TAG # This value cannot be modified

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

Example:

v1.2.3
BUILDKITE_TIMEOUT # This value cannot be modified

The number of minutes until Buildkite automatically cancels this job, if a timeout has been specified. Jobs that time out with an exit status of 0 are marked as "passed".

Example:

"15" for 15 minutes, or "false" if no timeout is set
BUILDKITE_TRACING_BACKEND #

Default:

This value cannot be modified

Set to "datadog" to send metrics to the Datadog APM using localhost:8126, or DD_AGENT_HOST:DD_AGENT_APM_PORT.

Also available as a buildkite agent configuration option.

Example:

datadog
BUILDKITE_TRIGGERED_FROM_BUILD_ID # This value cannot be modified

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
BUILDKITE_TRIGGERED_FROM_BUILD_NUMBER # This value cannot be modified

The number of the build that triggered this build.

Example:

"1264", or "" if the build was not triggered from another build
BUILDKITE_TRIGGERED_FROM_BUILD_PIPELINE_SLUG # This value cannot be modified

The slug of the pipeline that was used to trigger this build.

Example:

"build-and-test", or "" if the build was not triggered from another build
BUILDKITE_UNBLOCKER # This value cannot be modified

The name of the user who unblocked the build.

Example:

Carol Danvers
BUILDKITE_UNBLOCKER_EMAIL # This value cannot be modified

The notification email of the user who unblocked the build.

Example:

carol@nasa.gov
BUILDKITE_UNBLOCKER_ID # This value cannot be modified

The UUID of the user who unblocked the build.

Example:

4735ba57-80d0-46e2-8fa0-b28223a86586
BUILDKITE_UNBLOCKER_TEAMS # This value cannot be modified

A colon separated list of non-private team slugs that the user who unblocked the build belongs to.

Example:

everyone:platform
CI # This value cannot be modified

Always `true".

Deprecated environment variables

The following environment variables have been deprecated.

BUILDKITE_PROJECT_PROVIDER This has been renamed to `BUILDKITE_PIPELINE_PROVIDER`.
BUILDKITE_PROJECT_SLUG This has been renamed to `BUILDKITE_PIPELINE_SLUG`.
BUILDKITE_SCRIPT_PATH This has been renamed to `BUILDKITE_COMMAND`
BUILDKITE_STEP_IDENTIFIER This has been renamed to `BUILDKITE_STEP_KEY`
BUILDBOX_AGENT_ID This has been renamed to `BUILDKITE_AGENT_ID`
BUILDBOX_AGENT_NAME This has been renamed to `BUILDKITE_AGENT_NAME`
BUILDBOX_AGENT_META_DATA_* This has been renamed to `BUILDKITE_AGENT_META_DATA_*`
BUILDBOX_AGENT_ACCESS_TOKEN This has been renamed to `BUILDKITE_AGENT_ACCESS_TOKEN`
BUILDBOX_AGENT_API_URL This has been removed with no replacement

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.

Secrets in environment variables

Do not print or export secrets in your pipelines. See the Secrets documentation for further information and best practices.

Variable interpolation

Any environment variables set by Buildkite will be interpolated by the Agent.

If you're using the YAML Steps editor to define your pipeline, only the following subset of the environment variables are available:

  • BUILDKITE_BRANCH
  • BUILDKITE_TAG
  • BUILDKITE_MESSAGE
  • BUILDKITE_COMMIT
  • BUILDKITE_PIPELINE_SLUG
  • BUILDKITE_PIPELINE_NAME
  • BUILDKITE_PIPELINE_ID
  • BUILDKITE_ORGANIZATION_SLUG
  • BUILDKITE_TRIGGERED_FROM_BUILD_PIPELINE_SLUG
  • BUILDKITE_REPO
  • BUILDKITE_PULL_REQUEST
  • BUILDKITE_PULL_REQUEST_BASE_BRANCH
  • BUILDKITE_PULL_REQUEST_REPO

Some variables, for example BUILDKITE_BUILD_NUMBER, cannot be supported in the YAML Step editor as the interpolation happens before the build is created. In those cases, interpolate them at the runtime.

Alternatively, You can also access the rest of the Buildkite environment variables by using a pipeline.yml file. Either define your entire pipeline in the YAML file, or you do a pipeline upload part way through your build that adds only the steps that use environment variables. See the dynamic pipelines docs for more information about adding steps with pipeline uploads.

Runtime variable interpolation

When using environment variables that will be evaluated at run-time, make sure you escape the $ character using $$ or \$. For example:

- command: "deploy.sh $$SERVER"
  env:
    SERVER: "server-a"

Further details about environment variable interpolation can be found in the pipeline upload cli guide.

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.

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.

If you are not using YAML Steps, the precedence of environment variables is different from the list below.

Please migrate your pipelines to use YAML steps.

The job environment is made by merging the following sets of values, where values in each successive set take precedence:

Pipeline Optional variables set by you on a pipeline on the Pipeline Settings page
Build Optional variables set by you on the build when creating a new build in the UI or using the REST API
Step Optional variables set by you on a step in the YAML steps editor or a pipeline.yml file
Standard The set of variables provided by Buildkite to every job

For example, if you had configured the following environment variables:

Pipeline MY_ENV1="a"
Build MY_ENV1="b"
Step MY_ENV1="c"

In the final job environment, the value of MY_ENV1 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. This includes further pipeline uploads through buildkite-agent pipeline upload.

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 (for example, 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 hooks that have been defined by your agent, your repository or 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.