Buildkite Agent Configuration

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.

Example Configuration File

token="24db61df8338027652b24aadf82dd483b016eef98fcd332815"
name="my-app-%n"
tags="ci=true,docker=true"
git-clean-flags="-fdqx"
debug=true

Configuration Settings

Required attributes:

token The agent registration token from your organization’s Agents page, used only to register new agents

Environment variable: BUILDKITE_AGENT_TOKEN

Optional attributes:

bootstrap-script Command to invoke the bootstrap process

Default: "buildkite-agent bootstrap"

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

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

disconnect-after-job Disconnect after processing a single job

Default: false

Environment variable: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB

disconnect-after-job-timeout When `disconnect-after-job` is specified, the number of seconds to wait for a job before shutting down

Default: 120

Environment variable: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB_TIMEOUT

git-clean-flags Flags to pass to the git clean command. Prior to 3.0 this defaulted to "-fdq"

Default: "-fxdq"

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

hooks-path Directory where the global hook scripts are found

Default: (depends on platform)

Environment variable: BUILDKITE_HOOKS_PATH

name The name of the agent

Default: "%hostname-%n"

Environment variable: BUILDKITE_AGENT_NAME

no-color Do not show colors in logging

Default: false

Environment variable: BUILDKITE_AGENT_NO_COLOR

no-command-eval Do not allow this agent to run arbitrary console commands

Default: false

Environment variable: BUILDKITE_NO_COMMAND_EVAL

no-local-hooks Do not execute any local hooks

Default: false

Environment variable: BUILDKITE_AGENT_NO_LOCAL_HOOKS

no-plugins Do not load any plugins

Default: false

Environment variable: BUILDKITE_NO_PLUGINS

no-pty Do not run jobs within a pseudo terminal

Default: false

Environment variable: BUILDKITE_NO_PTY

no-ssh-keyscan Don't automatically run ssh-keyscan before checkout

Default: false

Environment variable: BUILDKITE_NO_SSH_KEYSCAN

plugins-path Directory where the plugins are saved

Default: (depends on platform)

Environment variable: BUILDKITE_PLUGINS_PATH

priority The priority of the agent (higher priorities are assigned work first, null is assigned last)

Default: null

Environment variable: BUILDKITE_AGENT_PRIORITY

shell The shell command used to interpret build commands, e.g /bin/bash -e -c

Default: "C:\Windows\System32\CMD.exe" on Windows, "/bin/bash" on *nix systems

Environment variable: BUILDKITE_SHELL

tags Tags for the agent

Default: "queue=default"

Environment variable: BUILDKITE_AGENT_TAGS

tags-from-ec2 Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as tags

Default: false

Environment variable: BUILDKITE_AGENT_TAGS_FROM_EC2

tags-from-ec2-tags Include the host's EC2 tags as agent tags

Default: false

Environment variable: BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS

wait-for-ec2-tags-timeout The amount of time to wait for tags from EC2 before proceeding

Default: 10s

Environment variable: BUILDKITE_AGENT_WAIT_FOR_EC2_TAGS_TIMEOUT

tags-from-gcp Include the host's Google Cloud meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)

Default: false

Environment variable: BUILDKITE_AGENT_TAGS_FROM_GCP

tags-from-host Include the host's meta-data as tags (`hostname`, `machine-id`, and `os`)

Default: false

Environment variable: BUILDKITE_AGENT_TAGS_FROM_HOST

timestamp-lines Prepend timestamps on each line of output

Default: false

Environment variable: BUILDKITE_TIMESTAMP_LINES

Deprecated Configuration Settings

meta-data Meta data for the agent

Default: "queue=default"

Environment variable: BUILDKITE_AGENT_META_DATA

Use instead: tags

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

Use instead: tags-from-ec2

meta-data-ec2-tags Include the host's EC2 tags as meta-data

Default: false

Environment variable: BUILDKITE_AGENT_META_DATA_EC2_TAGS

Use instead: tags-from-ec2-tags

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

Use instead: no-ssh-keyscan

Environment Variables

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

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

These variables cannot be modified through the Buildkite web interface, API or via 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.