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.
For best practices and recommendations about using secrets in your environment variables, see the Managing Secrets guide.
On this page:
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_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_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 via 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 via 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_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_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_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_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_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. The value cannot be modified.
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. 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"
BUILDKITE_TRACING_BACKEND
Set to "datadog"
to send metrics to the Datadog APM via localhost:8126
, or DD_AGENT_HOST:DD_AGENT_APM_PORT
.
Defaults to empty string. Also available as a buildkite agent configuration option.
Example: "datadog"
CI
Always "true"
. The value cannot be modified.
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` |
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
orpre-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 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.
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 via 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:
- In the
env
attribute 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.