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


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

token # Required

Environment variable:

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:

Default value: (depends on platform)

Path to where the builds will run from.

bootstrap-script # Optional

Environment variable:

Default value: buildkite-agent bootstrap

Command to invoke the bootstrap process.

cancel-grace-period # Optional

Environment variable:

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:

Default value: SIGTERM

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

debug # Optional

Environment variable:

Default value: false

Enable debug mode.

debug-http # Optional

Environment variable:

Default value: false

Log all HTTP request and response bodies.

disconnect-after-job # Optional

Environment variable:

Default value: false

Disconnect after processing a single job.

disconnect-after-idle-timeout # Optional

Environment variable:

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:

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:

Default value:

The Agent endpoint.

experiment # Optional

Environment variable:

Default value: none

A list of experimental agent features you want to enable.

git-clean-flags # Optional

Environment variable:

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:

Default value: -v

Flags to pass to the git clone command.

git-clone-mirror-flags # Optional

Environment variable:

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:

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:

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:

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:

Default value: disabled

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

hooks-path # Optional

Environment variable:

Default value: (depends on platform)

The directory to use for agent hooks. See Hook locations for details.

log-format # Optional

Environment variable:

Default value: text

The format to use for the logger output.

metrics-datadog # Optional

Environment variable:

Default value: false

Send metrics to DogStatsD for Datadog. This will generate the following metrics (duration measured in milliseconds):

metrics-datadog-host # Optional

Environment variable:

Default value:

The DogStatsD instance to send metrics to using UDP.

name # Optional

Environment variable:

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:

Default value: false

Do not show colors in logging.

no-command-eval # Optional

Environment variable:

Default value: false

Do not allow this agent to run arbitrary console commands.

no-git-submodules # Optional

Environment variable:

Default value: false

Do not automatically checkout git submodules.

no-http2 # Optional

Environment variable:

Default value: false

Disable HTTP2 when communicating with the Agent API.

no-local-hooks # Optional

Environment variable:

Default value: false

Do not execute any local hooks, or plugins from any source.

no-plugins # Optional

Environment variable:

Default value: false

Do not load any plugins.

no-plugin-validation # Optional

Environment variable:

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:

Default value: false

Do not run jobs within a pseudo terminal.

no-ssh-keyscan # Optional

Environment variable:

Default value: false

Do not automatically run ssh-keyscan before checkout.

plugins-path # Optional

Environment variable:

Default value: (depends on platform)

Directory where the plugins are saved.

plugins-always-clone-fresh # Optional

Environment variable:

Default value: false

Force checking out a fresh clone of plugins every build. By default, if the organisation, 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.

priority # Optional

Environment variable:

Default value: null

The priority of the agent. Higher priorities are assigned work first, null is assigned last.

redacted-vars # Optional

Environment variable:

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:

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:

Default value: 1

The number of agents to spawn in parallel.

tags # Optional

Environment variable:

Default value: queue=default

Tags for the agent.

tags-from-ec2 # Optional

Environment variable:

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:

Default value: false

Include the host's EC2 tags as agent tags.

tags-from-gcp # Optional

Environment variable:

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:

Default value: false

Include the host's Google Cloud instance labels as tags.

tags-from-host # Optional

Environment variable:

Default value: fals

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

timestamp-lines # Optional

Environment variable:

Default value: false

Prepend timestamps on each line of output.

tracing-backend # Optional

Environment variable:

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:

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:

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


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


Use instead: tags-from-ec2-tags

meta-data-gcp Include the host's GCP meta-data as meta-data.

Default: false


Use instead: tags-from-gcp

no-automatic-ssh-fingerprint-verification Do not automatically verify SSH fingerprints for first-time checkouts.

Default: false


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.