Buildkite Agent configuration

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

Example configuration file

/buildkite/buildkite-agent.cfg
token="24db61df8338027652b24aadf82dd483b016eef98fcd332815"
name="my-app-%spawn"
tags="ci=true,docker=true"
git-clean-flags="-ffdqx"
debug=true

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

Configuration settings

Required
token # Required

Environment variable:
BUILDKITE_AGENT_TOKEN

Default value: None

The agent registration token from your organization’s Agents page, used only to register new agents. To get your token, log in to Buildkite, navigate to Agents, then select Reveal Agent Token.
build-path # Required

Environment variable:
BUILDKITE_BUILD_PATH

Default value: (depends on platform)

Path to where the builds will run from.
Optional
bootstrap-script # Optional

Environment variable:
BUILDKITE_BOOTSTRAP_SCRIPT_PATH

Default value: buildkite-agent bootstrap

Command to invoke the bootstrap process.
cancel-grace-period # Optional

Environment variable:
BUILDKITE_CANCEL_GRACE_PERIOD

Default value: 10

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

Environment variable:
BUILDKITE_CANCEL_SIGNAL

Default value: SIGTERM

The signal that the agent sends to the bootstrap to signal cancellation.
debug # Optional

Environment variable:
BUILDKITE_AGENT_DEBUG

Default value: false

Enable debug mode.
debug-http # Optional

Environment variable:
BUILDKITE_AGENT_DEBUG_HTTP

Default value: false

Log all HTTP request and response bodies.
disconnect-after-job # Optional

Environment variable:
BUILDKITE_AGENT_DISCONNECT_AFTER_JOB

Default value: false

Disconnect after processing a single job.
disconnect-after-idle-timeout # Optional

Environment variable:
BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT

Default value: none

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.
enable-job-log-tmpfile # Optional

Environment variable:
BUILDKITE_ENABLE_JOB_LOG_TMPFILE

Default value: false

Enables the writing of job logs into a temporary file which can be accessed via the BUILDKITE_JOB_LOG_TMPFILE environment variable. Introduced in v3.36.
endpoint # Optional

Environment variable:
BUILDKITE_AGENT_ENDPOINT

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

The Agent endpoint.
experiment # Optional

Environment variable:
BUILDKITE_AGENT_EXPERIMENT

Default value: none

A list of experimental agent features you want to enable.
git-clean-flags # Optional

Environment variable:
BUILDKITE_GIT_CLEAN_FLAGS

Default value: -ffxdq

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".
git-clone-flags # Optional

Environment variable:
BUILDKITE_GIT_CLONE_FLAGS

Default value: -v

Flags to pass to the git clone command.
git-clone-mirror-flags # Optional

Environment variable:
BUILDKITE_GIT_CLONE_MIRROR_FLAGS

Default value: none

🛠 Experimental feature

Flags to pass to the git clone command when used for mirroring. Refer to Git mirrors for more information on this feature. This is an experimental feature. To use it, set experiment="git-mirrors" in your agent configuration. Learn more about Experimental features. Example: -v --mirror.
git-fetch-flags # Optional

Environment variable:
BUILDKITE_GIT_FETCH_FLAGS

Default value: -v --prune

🛠 Experimental feature

Flags to pass to the git fetch command. Before running builds on git tags, make sure your agent is fetching git tags.
git-mirrors-lock-timeout # Optional

Environment variable:
BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT

Default value: 300

🛠 Experimental feature

Seconds to lock a git mirror during clone. Should exceed your longest checkout. Refer to Git mirrors for more information on this feature. This is an experimental feature. To use it, set experiment="git-mirrors" in your agent configuration. Learn more about Experimental features.
git-mirrors-path # Optional

Environment variable:
BUILDKITE_GIT_MIRRORS_PATH

Default value: none

🛠 Experimental feature

Path to where mirrors of git repositories are stored. Refer to Git mirrors for more information on this feature. This is an experimental feature. To use it, set experiment="git-mirrors" in your agent configuration. Learn more about Experimental features. Example: /tmp/buildkite-git-mirrors
health-check-addr # Optional

Environment variable:
BUILDKITE_AGENT_HEALTH_CHECK_ADDR

Default value: disabled

Start an HTTP server on the specified address:port that returns whether the agent is healthy.
hooks-path # Optional

Environment variable:
BUILDKITE_HOOKS_PATH

Default value: (depends on platform)

The directory to use for agent hooks. See Hook locations for details.
log-format # Optional

Environment variable:
BUILDKITE_LOG_FORMAT

Default value: text

The format to use for the logger output.
metrics-datadog # Optional

Environment variable:
BUILDKITE_METRICS_DATADOG

Default value: false

Send metrics to DogStatsD for Datadog. This will generate the following metrics (duration measured in milliseconds): buildkite.jobs.success buildkite.jobs.duration.success.avg buildkite.jobs.duration.success.max buildkite.jobs.duration.success.count buildkite.jobs.duration.success.median buildkite.jobs.duration.success.95percentile
metrics-datadog-host # Optional

Environment variable:
BUILDKITE_METRICS_DATADOG_HOST

Default value: 127.0.0.1:8125

The DogStatsD instance to send metrics to using UDP.
metrics-datadog-distributions # Optional

Environment variable:
BUILDKITE_METRICS_DATADOG_DISTRIBUTIONS

Default value: false

Use Datadog Distributions for timing metrics. This is advisable when running multiple agents. Otherwise, metrics from multiple agents may be rolled up and appear to have the same value.
name # Optional

Environment variable:
BUILDKITE_AGENT_NAME

Default value: %hostname-%spawn

The name of the agent. Supports template variables.

  • %hostname (the agent machine's hostname)
  • %spawn (a unique number for each agent started using --spawn; added in v3.27.0).
  • %random (some random alphanumeric characters).
  • %pid (the agent process id).

Note that if you're using --spawn to run multiple agents in a single process, we recommend using %spawn in your agent name, or to ensure that each agent running on a host with the same build-path has a unique name.

Default on Elastic CI Stack for AWS: "%hostname-%spawn" (v5.2.0 and later).
no-color # Optional

Environment variable:
BUILDKITE_AGENT_NO_COLOR

Default value: false

Do not show colors in logging.
no-command-eval # Optional

Environment variable:
BUILDKITE_NO_COMMAND_EVAL

Default value: false

Do not allow this agent to run arbitrary console commands.
no-git-submodules # Optional

Environment variable:
BUILDKITE_NO_GIT_SUBMODULES, BUILDKIT_DISABLE_GIT_SUBMODULES

Default value: false

Do not automatically checkout git submodules.
no-http2 # Optional

Environment variable:
BUILDKITE_NO_HTTP2

Default value: false

Disable HTTP2 when communicating with the Agent API.
no-local-hooks # Optional

Environment variable:
BUILDKITE_NO_LOCAL_HOOKS

Default value: false

Do not execute any local hooks, or plugins from any source.
no-plugins # Optional

Environment variable:
BUILDKITE_NO_PLUGINS

Default value: false

Do not load any plugins.
no-plugin-validation # Optional

Environment variable:
BUILDKITE_NO_PLUGIN_VALIDATION

Default value: true

Do not validate plugin configuration and requirements. By default the option is enabled, so the validation is not performed.
no-pty # Optional

Environment variable:
BUILDKITE_NO_PTY

Default value: false

Do not run jobs within a pseudo terminal.
no-ssh-keyscan # Optional

Environment variable:
BUILDKITE_NO_SSH_KEYSCAN

Default value: false

Do not automatically run ssh-keyscan before checkout.
plugins-path # Optional

Environment variable:
BUILDKITE_PLUGINS_PATH

Default value: (depends on platform)

Directory where the plugins are saved.
plugins-always-clone-fresh # Optional

Environment variable:
BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH

Default value: false

Force checking out a fresh clone of plugins every build. By default, if the organization, repository, and version tag of a plugin specified in a step match a plugin that is already on the agent, the agent uses that local version. Forcing fresh checkout is especially useful during plugin development. Available from v3.37.
priority # Optional

Environment variable:
BUILDKITE_AGENT_PRIORITY

Default value: null

The priority of the agent. Higher priorities are assigned work first, null is assigned last.
redacted-vars # Optional

Environment variable:
BUILDKITE_REDACTED_VARS

Default value: '*_PASSWORD', '*_SECRET', '*_TOKEN', '*_ACCESS_KEY', '*_SECRET_KEY'

A list of environment variable name patterns whose values should be redacted before being printed to the build log. To disable redaction, set this to an empty string. Introduced in v3.31.
shell # Optional

Environment variable:
BUILDKITE_SHELL

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

The shell command used to interpret build commands. Example: /bin/bash -e -c.
spawn # Optional

Environment variable:
BUILDKITE_AGENT_SPAWN

Default value: 1

The number of agents to spawn in parallel.
tags # Optional

Environment variable:
BUILDKITE_AGENT_TAGS

Default value: queue=default

Tags for the agent.
tags-from-ec2 # Optional

Environment variable:
BUILDKITE_AGENT_TAGS_FROM_EC2

Default value: false

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

Environment variable:
BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS

Default value: false

Include the host's EC2 tags as agent tags.
tags-from-gcp # Optional

Environment variable:
BUILDKITE_AGENT_TAGS_FROM_GCP

Default value: false

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

Environment variable:
BUILDKITE_AGENT_TAGS_FROM_GCP_LABELS

Default value: false

Include the host's Google Cloud instance labels as tags.
tags-from-host # Optional

Environment variable:
BUILDKITE_AGENTS_TAGS_FROM_HOST

Default value: false

Include the host's meta-data as tags (hostname, machine-id, and OS).
timestamp-lines # Optional

Environment variable:
BUILDKITE_TIMESTAMP_LINES

Default value: false

Prepend timestamps on each line of output.
tracing-backend # Optional

Environment variable:
BUILDKITE_TRACING_BACKEND

Default value: none

Set to datadog to enable the Datadog API tracing for builds using the default APM address localhost:8126, or Datadog variables like DD_AGENT_HOST and DD_AGENT_TRACE_PORT. Set to opentelemetry to enable OpenTelemetry tracing, sending OTLP gRPC traces to https://localhost:4317, or override with the environment variable OTEL_EXPORTER_OTLP_ENDPOINT. Accepts empty string (""), "datadog", or opentelemetry.
wait-for-ec2-tags-timeout # Optional

Environment variable:
BUILDKITE_AGENT_WAIT_FOR_EC2_TAGS_TIMEOUT

Default value: 10

The amount of time in seconds to wait for tags from EC2 before proceeding.
wait-for-gcp-labels-timeout # Optional

Environment variable:
BUILDKITE_AGENT_WAIT_FOR_GCP_LABELS_TIMEOUT

Default value: 10

The amount of time in seconds to wait for tags from GCP before proceeding.

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.
Not to be confused with default and maximum build timeouts

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_GCP_TAGS

Use instead: tags-from-gcp
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 using pipeline upload for security reasons. You may be able to modify some of the options, such as BUILDKITE_GIT_CLONE_FLAGS, from within hooks.