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.

Flags to pass to the git clone command when used for mirroring. Refer to Git mirrors for more information on this feature. Introduced in v3.47.0 . Example: -v --mirror .

Path to where mirrors of git repositories are stored. Refer to Git mirrors for more information on this feature. Introduced in v3.47.0 . Example: /tmp/buildkite-git-mirrors

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


   %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).

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 .

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 .


   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 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

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

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.