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="-ffdqx"
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

cancel-grace-period The number of seconds a canceled or timed out job is given to gracefully terminate and upload its artifacts.

Default: 10

Environment variable: BUILDKITE_CANCEL_GRACE_PERIOD

cancel-signal The signal that the agent sends to the bootstrap to signal cancellation.

Default: SIGTERM

Environment variable: BUILDKITE_CANCEL_SIGNAL

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-idle-timeout The number of idle seconds to wait before shutting down. When setting this option alongside spawn, all agents started by spawn must be idle before the timeout counter will begin. After the timeout, the spawned agents will all disconnect.

Example: 10

Environment variable: BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT

endpoint The Agent endpoint.

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

Environment variable: BUILDKITE_AGENT_ENDPOINT

experiment A list of the experimental agent features to enable.

Example: "experiment1,experiment2"

Environment variable: BUILDKITE_AGENT_EXPERIMENT

git-clean-flags Flags to pass to the git clean command.
Agents below v3.0.0 default to "-fdq".
Agents v3.0.0 to v3.7.0 default to "-fxdq".

Default: "-ffxdq"

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

git-clone-mirror-flags Flags to pass to the git clone command when used for mirroring. This is an experimental flag.
Must set the experiment option with the git-mirror value, and the git-mirrors-path option.

Example: "-v --mirror"

Environment variable: BUILDKITE_GIT_CLONE_MIRROR_FLAGS

git-fetch-flags Flags to pass to the git fetch command.

Default: "-v --prune"

Environment variable: BUILDKITE_GIT_FETCH_FLAGS

git-mirrors-lock-timeout Seconds to lock a git mirror during clone, should exceed your longest checkout. This is an experimental flag.
Must set the experiment option with the git-mirror value, and the git-mirrors-path option.

Default: 300

Environment variable: BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT

git-mirrors-path Path to where mirrors of git repositories are stored. This is an experimental flag.
Must set the experiment option with the git-mirror value.

Example: /tmp/buildkite-git-mirrors

Environment variable: BUILDKITE_GIT_MIRRORS_PATH

health-check-addr Start an HTTP server on the specified address:port that returns whether the agent is healthy.

Default: disabled

Environment variable: BUILDKITE_AGENT_HEALTH_CHECK_ADDR

hooks-path Directory where the global hook scripts are found.

Default: (depends on platform)

Environment variable: BUILDKITE_HOOKS_PATH

log-format The format to use for the logger output.

Default: text

Environment variable: BUILDKITE_LOG_FORMAT

metrics-datadog Send metrics to DogStatsD for Datadog.

Default: false

Environment variable: BUILDKITE_METRICS_DATADOG

metrics-datadog-host The DogStatsD instance to send metrics to via udp.

Default: 127.0.0.1:8125

Environment variable: BUILDKITE_METRICS_DATADOG_HOST

name The name of the agent. Supports the template variables %hostname (the agent machine’s hostname) and %n (a unique number for 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-git-submodules Do not automatically checkout git submodules.

Default: false

Environment variable: BUILDKITE_NO_GIT_SUBMODULES, BUILDKITE_DISABLE_GIT_SUBMODULES

no-http2 Disable HTTP2 when communicating with the Agent API.

Default: false

Environment variable: BUILDKITE_NO_HTTP2

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-plugin-validation Do not validate plugin configuration and requirements.

Default: false

Environment variable: BUILDKITE_NO_PLUGIN_VALIDATION

no-pty Do not run jobs within a pseudo terminal.

Default: false

Environment variable: BUILDKITE_NO_PTY

no-ssh-keyscan Do not 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

spawn The number of agents to spawn in parallel.

Default: 1

Environment variable: BUILDKITE_AGENT_SPAWN

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

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-gcp-labels Include the host's Google Cloud instance labels as tags.

Default: false

Environment variable: BUILDKITE_AGENT_TAGS_FROM_GCP_LABELS

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

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

wait-for-gcp-labels-timeout The amount of time to wait for labels from GCP before proceeding.

Default: 10s

Environment variable: BUILDKITE_AGENT_WAIT_FOR_GCP_LABELS_TIMEOUT

Deprecated Configuration Settings

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

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

meta-data-gcp Include the host's GCP meta-data 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.