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, hooks.

BUILDKITE

Always "true".

BUILDKITE_AGENT_ACCESS_TOKEN

The agent session token for the job. The variable is read by the agent’s artifact and meta-data commands. The value cannot be modified.

Example: "83d544ccc223c157d2bf80d3f2a32982c32c3c0db8e3674820da5064783fb091"

BUILDKITE_AGENT_DEBUG

The value of the debug agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_AGENT_DISCONNECT_AFTER_JOB

The value of the disconnect-after-job agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT

The value of the disconnect-after-idle-timeout agent configuration option. The value cannot be modified as an environment variable.

Example: "10"

BUILDKITE_AGENT_ENDPOINT

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

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

BUILDKITE_AGENT_EXPERIMENT

A list of the experimental agent features that are currently enabled. The value cannot be modified as an environment variable. 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

The value of the health-check-addr agent configuration option. The value cannot be modified as an environment variable.

Example: "localhost:8080"

BUILDKITE_AGENT_ID

The UUID of the agent. The value cannot be modified as an environment variable.

Example: "1a222222-e999-3636-8ddd-802222222222"

BUILDKITE_AGENT_META_DATA_*

The value of each agent tag. The tag name is appended to the end of the variable name. The name and value cannot be modified as an environment variable. 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

The name of the agent that ran the job. The value cannot be modified as an environment variable.

Example: "elastic-builders-088264dc4f9"

BUILDKITE_AGENT_PID

The process ID of the agent. The value cannot be modified.

Example: "6"

BUILDKITE_ARTIFACT_PATHS

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

The path to the directory containing the buildkite-agent binary. The value cannot be modified as an environment variable.

Example: "/usr/local/bin"

BUILDKITE_BRANCH

The branch being built. The value cannot be modified.

Example: "master"

BUILDKITE_BUILD_CHECKOUT_PATH

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

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

Example: "Carol Danvers"

BUILDKITE_BUILD_AUTHOR_EMAIL

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

Example: "cdanvers@kree-net.com"

BUILDKITE_BUILD_CREATOR

The name of the user who created the build. The value cannot be modified.

Example: "Carol Danvers"

BUILDKITE_BUILD_CREATOR_EMAIL

The notification email of the user who created the build. The value cannot be modified.

Example: "cdanvers@kree-net.com"

BUILDKITE_BUILD_CREATOR_TEAMS

A colon separated list of non-private team names that the build creator belongs to. The value cannot be modified.

Example: "everyone:platform"

BUILDKITE_BUILD_ID

The UUID of the build. The value cannot be modified.

Example: "4735ba57-80d0-46e2-8fa0-b28223a86586"

BUILDKITE_BUILD_NUMBER

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

Example: "1514"

BUILDKITE_BUILD_PATH

The value of the build-path agent configuration option. The value cannot be modified as an environment variable.

Example: "/var/lib/buildkite-agent/builds/"

BUILDKITE_BUILD_URL

The url for this build on Buildkite. The value cannot be modified.

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

BUILDKITE_CANCEL_GRACE_PERIOD

The value of the cancel-grace-period agent configuration option. The value cannot be modified as an environment variable.

Default: 10

BUILDKITE_CANCEL_SIGNAL

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.

Default: SIGTERM

BUILDKITE_CLEAN_CHECKOUT

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.

Values: "true" or "false"

BUILDKITE_COMMAND

The command that will be run for the job. The value cannot be modified.

Example: "script/buildkite/specs"

BUILDKITE_COMMAND_EVAL

The opposite of the value of the no-command-eval agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_COMMAND_EXIT_STATUS

The exit code from the last command run in the command hook. The value cannot be modified.

Example: "-1"

BUILDKITE_COMMIT

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. The value cannot be modified.

Example: "83a20ec058e2fb00e7fa4558c4c6e81e2dcf253d"

BUILDKITE_CONFIG_PATH

The path to the agent config file. The value cannot be modified as an environment variable.

Default: "/buildkite/buildkite-agent.cfg"

BUILDKITE_ENV_FILE

The path to the file containing the job’s environment variables. The value cannot be modified.

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

The opposite of the value of the no-git-submodules agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_GITHUB_DEPLOYMENT_ID

The GitHub deployment ID. Only available on builds triggered by a GitHub Deployment. The value cannot be modified as an environment variable.

Example: "87972451"

BUILDKITE_GITHUB_DEPLOYMENT_ENVIRONMENT

The name of the GitHub deployment environment. Only available on builds triggered by a GitHub Deployment. The value cannot be modified as an environment variable.

Example: "production"

BUILDKITE_GITHUB_DEPLOYMENT_TASK

The name of the GitHub deployment task. Only available on builds triggered by a GitHub Deployment. The value cannot be modified as an environment variable.

Example: "deploy"

BUILDKITE_GITHUB_DEPLOYMENT_PAYLOAD

The GitHub deployment payload data as serialized JSON. Only available on builds triggered by a GitHub Deployment. The value cannot be modified as an environment variable.

Example: "production"

BUILDKITE_HOOKS_PATH

The value of the hooks-path agent configuration option. The value cannot be modified as an environment variable.

Example: "/etc/buildkite-agent/hooks/"

BUILDKITE_IGNORED_ENV

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. The value cannot be modified.

Example: "BUILDKITE_GIT_CLEAN_FLAGS"

BUILDKITE_JOB_ID

The internal UUID Buildkite uses for this job. The value cannot be modified.

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

BUILDKITE_LABEL

The label/name of the current job. The value cannot be modified.

Example: ":hammer: Specs"

BUILDKITE_LAST_HOOK_EXIT_STATUS

The exit code of the last hook that ran, used internally by the hooks. The value cannot be modified.

Example: "-1"

BUILDKITE_LOCAL_HOOKS_ENABLED

The opposite of the value of the no-local-hooks agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_MESSAGE

The message associated with the build, usually the commit message. The value cannot be modified.

Example: "Added a great new feature"

BUILDKITE_ORGANIZATION_SLUG

The organization name on Buildkite as used in URLs. The value cannot be modified.

Example: "acme-inc"

BUILDKITE_PARALLEL_JOB

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

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

The default branch for this pipeline. The value cannot be modified.

Example: "master"

BUILDKITE_PIPELINE_NAME

The displayed pipeline name on Buildkite. The value cannot be modified.

Example: "my_project"

BUILDKITE_PIPELINE_PROVIDER

The ID of the source code provider for the pipeline’s repository. The value cannot be modified.

Example: "github"

BUILDKITE_PIPELINE_SLUG

The pipeline slug on Buildkite as used in URLs. The value cannot be modified.

Example: "my-project"

BUILDKITE_PLUGINS

A JSON object containing 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

The opposite of the value of the no-plugins agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_PLUGINS_PATH

The value of the plugins-path agent configuration option. The value cannot be modified as an environment variable.

Example: "/etc/buildkite-agent/plugins/"

BUILDKITE_PLUGIN_VALIDATION

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.

Default: "false"

BUILDKITE_PULL_REQUEST

The number of the pull request, if this branch is a pull request. The value cannot be modified.

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 targeting. The value cannot be modified.

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

BUILDKITE_PULL_REQUEST_REPO

The repository URL of the pull request. The value cannot be modified.

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. The value cannot be modified.

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. The value cannot be modified.

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

BUILDKITE_REFSPEC

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

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

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

Example: "/tmp/buildkite-git-mirrors"

BUILDKITE_RETRY_COUNT

How many times this job has been retried. The value cannot be modified.

Example: "0"

BUILDKITE_S3_ACCESS_KEY_ID

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

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

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.

Values: "private","public-read-write","public-read", "authenticated-read","bucket-owner-read","bucket-owner-full-control"

Default: "public-read"

BUILDKITE_S3_DEFAULT_REGION

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.

Default: "us-east-1"

BUILDKITE_S3_SECRET_ACCESS_KEY

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

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.

Default: false

BUILDKITE_SHELL

The value of the shell agent configuration option. The value cannot be modified as an environment variable.

Example: "/bin/bash -e -c"

BUILDKITE_SOURCE

The source of the event that created the build. The value cannot be modified.

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

BUILDKITE_SSH_KEYSCAN

The opposite of the value of the no-ssh-keyscan agent configuration option. The value cannot be modified as an environment variable.

Values: "true" and "false"

BUILDKITE_STEP_ID

A unique string that identifies a step. This value cannot be modified.

Example: "080b7d73-986d-4a39-a510-b34f9faf4710"

BUILDKITE_STEP_KEY

The value of the key command step attribute, a unique string set by you to identify a step. This value cannot be modified as an environment variable.

Example: "tests-06"

BUILDKITE_TAG

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

Example: "v1.2.3"

BUILDKITE_TIMEOUT

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". The value cannot be modified.

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

BUILDKITE_TRACING_BACKEND

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

Defaults to empty string. Also available as a buildkite agent configuration option.

Example: "datadog"

BUILDKITE_TRIGGERED_FROM_BUILD_ID

The UUID of the build that triggered this build. The value cannot be modified.

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

BUILDKITE_TRIGGERED_FROM_BUILD_NUMBER

The number of the build that triggered this build. The value cannot be modified.

Example: "1264", or "" if the build was not triggered from another build.

BUILDKITE_TRIGGERED_FROM_BUILD_PIPELINE_SLUG

The slug of the pipeline that was used to trigger this build. The value cannot be modified.

Example: "build-and-test", or "" if the build was not triggered from another build.

BUILDKITE_UNBLOCKER

The name of the user who unblocked the build. The value cannot be modified.

Example: "Carol Danvers"

BUILDKITE_UNBLOCKER_EMAIL

The notification email of the user who unblocked the build. The value cannot be modified.

Example: "carol@nasa.gov"

BUILDKITE_UNBLOCKER_ID

The UUID of the user who unblocked the build. The value cannot be modified.

Example: "4735ba57-80d0-46e2-8fa0-b28223a86586"

BUILDKITE_UNBLOCKER_TEAMS

A colon separated list of non-private team names that the user who unblocked the build belongs to. The value cannot be modified.

Example: "everyone:platform"

CI

Always "true". The value cannot be modified.

Deprecated environment variables

The following environment variables have been deprecated.

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.

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 a subset of the environment variables are available at this level. Some variables, for example BUILDKITE_BUILD_NUMBER, cannot be supported in the YAML Step editor as the interpolation happens before the build is created.

The following variables are available directly in the YAML Step editor:

• 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

You can 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.

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.

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

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

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.

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.

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.

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.