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
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:
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. |
Optional | |
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 |
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 |
endpoint #
Optional
Environment variable:
Default value: https://agent.buildkite.com/v3 |
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-clone-flags #
Optional
Environment variable:
Default value: -v |
Flags to pass to the |
git-clone-mirror-flags #
Optional
Environment variable:
Default value: none |
Flags to pass to the |
git-fetch-flags #
Optional
Environment variable:
Default value: -v --prune |
Flags to pass to the |
git-mirrors-lock-timeout #
Optional
Environment variable:
Default value: 300 |
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 |
git-mirrors-path #
Optional
Environment variable:
Default value: none |
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 |
health-check-addr #
Optional
Environment variable:
Default value: disabled |
Start an HTTP server on the specified |
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: 127.0.0.1:8125 |
The DogStatsD instance to send metrics to using UDP. |
metrics-datadog-distributions #
Optional
Environment variable:
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:
Default value: %hostname-%spawn |
The name of the agent. Supports template variables.
Note that if you're using Default on Elastic CI Stack for AWS: " |
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 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:
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: |
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: false |
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 |
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: Environment variable: |
---|---|
meta-data |
Meta data for the agent.
Default: Environment variable: |
meta-data-ec2 |
Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as meta-data.
Default: Environment variable: |
meta-data-ec2-tags |
Include the host's EC2 tags as meta-data.
Default: Environment variable: |
meta-data-gcp |
Include the host's GCP meta-data as meta-data.
Default: Environment variable: |
no-automatic-ssh-fingerprint-verification |
Do not automatically verify SSH fingerprints for first-time checkouts.
Default: Environment variable: |
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.