Buildkite Agent configuration

This page references the out-of-date Buildkite Agent v2.

For docs referencing the Buildkite Agent v3, see the latest version of this document.

Every agent installer comes with a configuration file. You can also customize many of the configuration values using environment variables.

You can find the location of your configuration file in your platform's installation documentation, or you can set it using the BUILDKITE_AGENT_CONFIG environment variable or the --config command line argument.

Configuration settings

token
The agent token from your organization's Agents page
Environment variable: BUILDKITE_AGENT_TOKEN

name
The name of the agent
Default: "%hostname-%spawn"
Environment variable: BUILDKITE_AGENT_NAME

priority
The priority of the agent (higher priorities are assigned work first, null is assigned last)
Default: null
Environment variable: BUILDKITE_AGENT_PRIORITY

meta-data
Meta data for the agent
Default: "queue=default"
Environment variable: BUILDKITE_AGENT_META_DATA

meta-data-ec2
Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as meta-data
Default: false
Environment variable: BUILDKITE_AGENT_META_DATA_EC2

meta-data-ec2-tags
Include the host's EC2 tags as meta-data
Default: false
Environment variable: BUILDKITE_AGENT_META_DATA_EC2_TAGS

git-clean-flags
Flags to pass to the git clean command
Default: "-fdq"
Environment variable: BUILDKITE_GIT_CLEAN_FLAGS

git-clone-flags
Flags to pass to the git clone command
Default: "-v"
Environment variable: BUILDKITE_GIT_CLONE_FLAGS

bootstrap-script
Path to the bootstrap script
Default: (depends on platform)
Environment variable: BUILDKITE_BOOTSTRAP_SCRIPT_PATH

build-path
Path to where the builds will run from
Default: (depends on platform)
Environment variable: BUILDKITE_BUILD_PATH

hooks-path
Directory where the global hook scripts are found
Default: (depends on platform)
Environment variable: BUILDKITE_HOOKS_PATH

no-pty
Do not run jobs within a pseudo terminal
Default: false
Environment variable: BUILDKITE_NO_PTY

no-automatic-ssh-fingerprint-verification
Do not automatically verify SSH fingerprints for first-time checkouts
Default: false
Environment variable: BUILDKITE_NO_AUTOMATIC_SSH_FINGERPRINT_VERIFICATION

no-command-eval
Do not allow this agent to run arbitrary console commands
Default: false
Environment variable: BUILDKITE_NO_COMMAND_EVAL

debug
Enable debug mode
Default: false
Environment variable: BUILDKITE_AGENT_DEBUG

debug-http
Log all HTTP request and response bodies
Default: false
Environment variable: BUILDKITE_AGENT_DEBUG_HTTP

no-color
Do not show colors in logging
Default: false
Environment variable: BUILDKITE_AGENT_NO_COLOR

timestamp-lines
Prepend timestamps on each line of output
Default: false
Environment variable: BUILDKITE_TIMESTAMP_LINES

Example configuration file

token="24db61df8338027652b24aadf82dd483b016eef98fcd332815"
name="my-app-%random"
meta-data="ci=true,docker=true"
git-clean-flags="-fdqx"
debug=true

Environment variables

Most configuration options can be specified as environment variables when starting the agent, for example:

BUILDKITE_AGENT_META_DATA="queue=deploy,host=$(hostname)" buildkite-agent start

These variables cannot be modified through the Buildkite web interface, API or using pipeline upload for security reasons. You may be able to modify some of the options, such as BUILDKITE_GIT_CLONE_FLAGS, from within hook scripts.