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 directory location of your configuration file in your platform's installation documentation. You can also set this folder using the --config command line argument or the BUILDKITE_AGENT_CONFIG environment variable.

BUILDKITE_AGENT_CONFIG="/etc/buildkite-agent/custom-config-files-dir" buildkite-agent start

Configuration settings

Required
`build-path#` Required Environment variable: `$BUILDKITE_BUILD_PATH`	Path to where the builds will run from
`token#` Required Environment variable: `$BUILDKITE_AGENT_TOKEN`	Your account agent token
Optional
`no-color#` Optional Environment variable: `$BUILDKITE_AGENT_NO_COLOR`	Don't show colors in logging
`debug#` Optional Environment variable: `$BUILDKITE_AGENT_DEBUG`	Enable debug mode. Synonym for ′--log-level debug′. Takes precedence over ′--log-level′
`log-level#` Optional Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL` Default value: `"notice"`	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal
`experiment#` Optional Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`	Enable experimental features within the buildkite-agent
`profile#` Optional Environment variable: `$BUILDKITE_AGENT_PROFILE`	Enable a profiling mode, either cpu, memory, mutex or block
`name#` Optional Environment variable: `$BUILDKITE_AGENT_NAME`	The name of the agent
`priority#` Optional Environment variable: `$BUILDKITE_AGENT_PRIORITY`	The priority of the agent (higher priorities are assigned work first)
`acquire-job#` Optional Environment variable: `$BUILDKITE_AGENT_ACQUIRE_JOB`	Start this agent and only run the specified job, disconnecting after it's finished
`reflect-exit-status#` Optional Environment variable: `$BUILDKITE_AGENT_REFLECT_EXIT_STATUS`	When used with --acquire-job, causes the agent to exit with the same exit status as the job
`disconnect-after-job#` Optional Environment variable: `$BUILDKITE_AGENT_DISCONNECT_AFTER_JOB`	Disconnect the agent after running exactly one job. When used in conjunction with the ′--spawn′ flag, each worker booted will run exactly one job
`disconnect-after-idle-timeout#` Optional Environment variable: `$BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT` Default value: `0`	The maximum idle time in seconds to wait for a job before disconnecting. The default of 0 means no timeout
`disconnect-after-uptime#` Optional Environment variable: `$BUILDKITE_AGENT_DISCONNECT_AFTER_UPTIME` Default value: `0`	The maximum uptime in seconds before the agent stops accepting new jobs and shuts down after any running jobs complete. The default of 0 means no timeout
`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
`enable-job-log-tmpfile#` Optional Environment variable: `$BUILDKITE_ENABLE_JOB_LOG_TMPFILE`	Store the job logs in a temporary file ′BUILDKITE_JOB_LOG_TMPFILE′ that is accessible during the job and removed at the end of the job
`job-log-path#` Optional Environment variable: `$BUILDKITE_JOB_LOG_PATH`	Location to store job logs created by configuring ′enable-job-log-tmpfile`, by default job log will be stored in TempDir
`write-job-logs-to-stdout#` Optional Environment variable: `$BUILDKITE_WRITE_JOB_LOGS_TO_STDOUT`	Writes job logs to the agent process' stdout. This simplifies log collection if running agents in Docker.
`shell#` Optional Environment variable: `$BUILDKITE_SHELL` Default value: `"/bin/bash -e -c"`	The shell command used to interpret build commands, e.g /bin/bash -e -c
`queue#` Optional Environment variable: `$BUILDKITE_AGENT_QUEUE`	The queue the agent will listen to for jobs. If not set, the agent will use the default queue. Overwrites the queue tag in the agent's tags
`tags#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS`	A comma-separated list of tags for the agent (for example, "linux" or "mac,xcode=8")
`tags-from-host#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_HOST`	Include tags from the host (hostname, machine-id, os)
`tags-from-ec2-meta-data#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_EC2_META_DATA`	Include the default set of host EC2 meta-data as tags (instance-id, instance-type, ami-id, and instance-life-cycle)
`tags-from-ec2-meta-data-paths#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_EC2_META_DATA_PATHS`	Include additional tags fetched from EC2 meta-data using tag & path suffix pairs, e.g "tag_name=path/to/value"
`tags-from-ec2-tags#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS`	Include the host's EC2 tags as tags
`tags-from-ecs-meta-data#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_ECS_META_DATA`	Include the host's ECS meta-data as tags (container-name, image, and task-arn)
`tags-from-gcp-meta-data#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_GCP_META_DATA`	Include the default set of host Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)
`tags-from-gcp-meta-data-paths#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_GCP_META_DATA_PATHS`	Include additional tags fetched from Google Cloud instance meta-data using tag & path suffix pairs, e.g "tag_name=path/to/value"
`tags-from-gcp-labels#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_GCP_LABELS`	Include the host's Google Cloud instance labels as tags
`wait-for-ec2-tags-timeout#` Optional Environment variable: `$BUILDKITE_AGENT_WAIT_FOR_EC2_TAGS_TIMEOUT` Default value: `10s`	The amount of time to wait for tags from EC2 before proceeding
`wait-for-ec2-meta-data-timeout#` Optional Environment variable: `$BUILDKITE_AGENT_WAIT_FOR_EC2_META_DATA_TIMEOUT` Default value: `10s`	The amount of time to wait for meta-data from EC2 before proceeding
`wait-for-ecs-meta-data-timeout#` Optional Environment variable: `$BUILDKITE_AGENT_WAIT_FOR_ECS_META_DATA_TIMEOUT` Default value: `10s`	The amount of time to wait for meta-data from ECS before proceeding
`wait-for-gcp-labels-timeout#` Optional Environment variable: `$BUILDKITE_AGENT_WAIT_FOR_GCP_LABELS_TIMEOUT` Default value: `10s`	The amount of time to wait for labels from GCP before proceeding
`git-checkout-flags#` Optional Environment variable: `$BUILDKITE_GIT_CHECKOUT_FLAGS` Default value: `"-f"`	Flags to pass to "git checkout" command
`git-clone-flags#` Optional Environment variable: `$BUILDKITE_GIT_CLONE_FLAGS` Default value: `"-v"`	Flags to pass to the "git clone" command
`git-clean-flags#` Optional Environment variable: `$BUILDKITE_GIT_CLEAN_FLAGS` Default value: `"-ffxdq"`	Flags to pass to "git clean" command
`git-fetch-flags#` Optional Environment variable: `$BUILDKITE_GIT_FETCH_FLAGS` Default value: `"-v --prune"`	Flags to pass to "git fetch" command
`git-clone-mirror-flags#` Optional Environment variable: `$BUILDKITE_GIT_CLONE_MIRROR_FLAGS` Default value: `"-v"`	Flags to pass to the "git clone" command when used for mirroring
`git-mirrors-path#` Optional Environment variable: `$BUILDKITE_GIT_MIRRORS_PATH`	Path to where mirrors of git repositories are stored
`git-mirrors-lock-timeout#` Optional Environment variable: `$BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT` Default value: `300`	Seconds to lock a git mirror during clone, should exceed your longest checkout
`git-mirrors-skip-update#` Optional Environment variable: `$BUILDKITE_GIT_MIRRORS_SKIP_UPDATE`	Skip updating the Git mirror
`bootstrap-script#` Optional Environment variable: `$BUILDKITE_BOOTSTRAP_SCRIPT_PATH`	The command that is executed for bootstrapping a job, defaults to the bootstrap sub-command of this binary
`hooks-path#` Optional Environment variable: `$BUILDKITE_HOOKS_PATH`	Directory where the hook scripts are found
`additional-hooks-paths#` Optional Environment variable: `$BUILDKITE_ADDITIONAL_HOOKS_PATHS`	Additional directories to look for agent hooks
`sockets-path#` Optional Environment variable: `$BUILDKITE_SOCKETS_PATH` Default value: `"~/.buildkite-agent/sockets"`	Directory where the agent will place sockets
`plugins-path#` Optional Environment variable: `$BUILDKITE_PLUGINS_PATH`	Directory where the plugins are saved to
`no-ansi-timestamps#` Optional Environment variable: `$BUILDKITE_NO_ANSI_TIMESTAMPS`	Do not insert ANSI timestamp codes at the start of each line of job output
`timestamp-lines#` Optional Environment variable: `$BUILDKITE_TIMESTAMP_LINES`	Prepend timestamps on each line of job output. Has no effect unless --no-ansi-timestamps is also used
`health-check-addr#` Optional Environment variable: `$BUILDKITE_AGENT_HEALTH_CHECK_ADDR`	Start an HTTP server on this addr:port that returns whether the agent is healthy, disabled by default
`no-pty#` Optional Environment variable: `$BUILDKITE_NO_PTY`	Do not run jobs within a pseudo terminal
`no-ssh-keyscan#` Optional Environment variable: `$BUILDKITE_NO_SSH_KEYSCAN`	Don't automatically run ssh-keyscan before checkout
`no-command-eval#` Optional Environment variable: `$BUILDKITE_NO_COMMAND_EVAL`	Don't allow this agent to run arbitrary console commands, including plugins
`no-plugins#` Optional Environment variable: `$BUILDKITE_NO_PLUGINS`	Don't allow this agent to load plugins
`no-plugin-validation#` Optional Environment variable: `$BUILDKITE_NO_PLUGIN_VALIDATION`	Don't validate plugin configuration and requirements
`plugins-always-clone-fresh#` Optional Environment variable: `$BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH`	Always make a new clone of plugin source, even if already present
`no-local-hooks#` Optional Environment variable: `$BUILDKITE_NO_LOCAL_HOOKS`	Don't allow local hooks to be run from checked out repositories
`no-git-submodules#` Optional Environment variable: `$BUILDKITE_NO_GIT_SUBMODULES $BUILDKITE_DISABLE_GIT_SUBMODULES`	Don't automatically checkout git submodules
`no-feature-reporting#` Optional Environment variable: `$BUILDKITE_AGENT_NO_FEATURE_REPORTING`	Disables sending a list of enabled features back to the Buildkite mothership. We use this information to measure feature usage, but if you're not comfortable sharing that information then that's totally okay :)
`allowed-repositories#` Optional Environment variable: `$BUILDKITE_ALLOWED_REPOSITORIES`	A comma-separated list of regular expressions representing repositories the agent is allowed to clone (for example, "^git@github.com:buildkite/." or "^https://github.com/buildkite/.")
`enable-environment-variable-allowlist#` Optional Environment variable: `$BUILDKITE_ENABLE_ENVIRONMENT_VARIABLE_ALLOWLIST`	Only run jobs where all environment variables are allowed by the allowed-environment-variables option, or have been set by Buildkite
`allowed-environment-variables#` Optional Environment variable: `$BUILDKITE_ALLOWED_ENVIRONMENT_VARIABLES`	A comma-separated list of regular expressions representing environment variables the agent will pass to jobs (for example, "^MYAPP_.*$"). Environment variables set by Buildkite will always be allowed. Requires --enable-environment-variable-allowlist to be set
`allowed-plugins#` Optional Environment variable: `$BUILDKITE_ALLOWED_PLUGINS`	A comma-separated list of regular expressions representing plugins the agent is allowed to use (for example, "^buildkite-plugins/.$" or "^/var/lib/buildkite-plugins/.")
`metrics-datadog#` Optional Environment variable: `$BUILDKITE_METRICS_DATADOG`	Send metrics to DogStatsD for Datadog
`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`	Use Datadog Distributions for Timing metrics
`log-format#` Optional Environment variable: `$BUILDKITE_LOG_FORMAT` Default value: `"text"`	The format to use for the logger output
`spawn#` Optional Environment variable: `$BUILDKITE_AGENT_SPAWN` Default value: `1`	The number of agents to spawn in parallel (mutually exclusive with --spawn-per-cpu)
`spawn-per-cpu#` Optional Environment variable: `$BUILDKITE_AGENT_SPAWN_PER_CPU` Default value: `0`	The number of agents to spawn per cpu in parallel (mutually exclusive with --spawn)
`spawn-with-priority#` Optional Environment variable: `$BUILDKITE_AGENT_SPAWN_WITH_PRIORITY`	Assign priorities to every spawned agent (when using --spawn or --spawn-per-cpu) equal to the agent's index
`cancel-signal#` Optional Environment variable: `$BUILDKITE_CANCEL_SIGNAL` Default value: `"SIGTERM"`	The signal to use for cancellation
`signal-grace-period-seconds#` Optional Environment variable: `$BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS` Default value: `-1`	The number of seconds given to a subprocess to handle being sent ′cancel-signal′. After this period has elapsed, SIGKILL will be sent. Negative values are taken relative to ′cancel-grace-period′. The default value (-1) means that the effective signal grace period is equal to ′cancel-grace-period′ minus 1.
`tracing-backend#` Optional Environment variable: `$BUILDKITE_TRACING_BACKEND`	Enable tracing for build jobs by specifying a backend, "datadog" or "opentelemetry"
`tracing-propagate-traceparent#` Optional Environment variable: `$BUILDKITE_TRACING_PROPAGATE_TRACEPARENT`	Enable accepting traceparent context from Buildkite control plane (only supported for OpenTelemetry backend)
`tracing-service-name#` Optional Environment variable: `$BUILDKITE_TRACING_SERVICE_NAME` Default value: `"buildkite-agent"`	Service name to use when reporting traces.
`verification-jwks-file#` Optional Environment variable: `$BUILDKITE_AGENT_VERIFICATION_JWKS_FILE`	Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.
`signing-jwks-file#` Optional Environment variable: `$BUILDKITE_AGENT_SIGNING_JWKS_FILE`	Path to a file containing a signing key. Passing this flag enables pipeline signing for all pipelines uploaded by this agent. For hmac-sha256, the raw file content is used as the shared key. When using Docker containers to upload pipeline steps dynamically, use environment variable propagation (for example, "docker run -e BUILDKITE_AGENT_JWKS_FILE") to allow all steps within the pipeline to be signed.
`signing-jwks-key-id#` Optional Environment variable: `$BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID`	The JWKS key ID to use when signing the pipeline. If omitted, and the signing JWKS contains only one key, that key will be used.
`signing-aws-kms-key#` Optional Environment variable: `$BUILDKITE_AGENT_SIGNING_AWS_KMS_KEY`	The KMS KMS key ID, or key alias used when signing and verifying the pipeline.
`debug-signing#` Optional Environment variable: `$BUILDKITE_AGENT_DEBUG_SIGNING`	Enable debug logging for pipeline signing. This can potentially leak secrets to the logs as it prints each step in full before signing. Requires debug logging to be enabled
`verification-failure-behavior#` Optional Environment variable: `block warn` Default value: `"block"`	The behavior when a job is received without a valid verifiable signature (without a signature, with an invalid signature, or with a signature that fails verification). One of: [block warn]. Defaults to block
`disable-warnings-for#` Optional Environment variable: `$BUILDKITE_AGENT_DISABLE_WARNINGS_FOR`	A list of warning IDs to disable
`endpoint#` Optional Environment variable: `$BUILDKITE_AGENT_ENDPOINT` Default value: `"https://agent.buildkite.com/v3"`	The Agent API endpoint
`no-http2#` Optional Environment variable: `$BUILDKITE_NO_HTTP2`	Disable HTTP2 when communicating with the Agent API.
`debug-http#` Optional Environment variable: `$BUILDKITE_AGENT_DEBUG_HTTP`	Enable HTTP debug mode, which dumps all request and response bodies to the log
`trace-http#` Optional Environment variable: `$BUILDKITE_AGENT_TRACE_HTTP`	Enable HTTP trace mode, which logs timings for each HTTP request. Timings are logged at the debug level unless a request fails at the network level in which case they are logged at the error level
`redacted-vars#` Optional Environment variable: `$BUILDKITE_REDACTED_VARS` Default value: `"_PASSWORD", "_SECRET", "_TOKEN", "_PRIVATE_KEY", "_ACCESS_KEY", "_SECRET_KEY", "*_CONNECTION_STRING"`	Pattern of environment variable names containing sensitive values
`strict-single-hooks#` Optional Environment variable: `$BUILDKITE_STRICT_SINGLE_HOOKS`	Enforces that only one checkout hook, and only one command hook, can be run
`kubernetes-exec#` Optional Environment variable: `$BUILDKITE_KUBERNETES_EXEC`	This is intended to be used only by the Buildkite k8s stack (github.com/buildkite/agent-stack-k8s); it enables a Unix socket for transporting logs and exit statuses between containers in a pod
`kubernetes-log-collection-grace-period#` Optional Environment variable: `$BUILDKITE_KUBERNETES_LOG_COLLECTION_GRACE_PERIOD` Default value: `50s`	How long to wait for Kubernetes processes to complete before stopping log collection during graceful termination. This should be less than the pod's terminationGracePeriodSeconds to allow time for final log upload
`trace-context-encoding#` Optional Environment variable: `$BUILDKITE_TRACE_CONTEXT_ENCODING` Default value: `"gob"`	Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob
`no-multipart-artifact-upload#` Optional Environment variable: `$BUILDKITE_NO_MULTIPART_ARTIFACT_UPLOAD`	For Buildkite-hosted artifacts, disables the use of multipart uploads. Has no effect on uploads to other destinations such as custom cloud buckets
`tags-from-ec2#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_EC2`	Include the host's EC2 meta-data as tags (instance-id, instance-type, and ami-id)
`tags-from-gcp#` Optional Environment variable: `$BUILDKITE_AGENT_TAGS_FROM_GCP`	Include the host's Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)

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.

Agent Naming

The following template variables are supported when configuring the agent name:

%hostname - the agent machine's hostname
%spawn - the spawn index number (1, 2, 3, etc.) when launching multiple agents per host
%random - six (6) random alphanumeric characters [a-zA-Z0-9]
%pid - the agent's process ID

Note

If you're using --spawn to run multiple agents on a single host, it's recommended to use %spawn in your agent name to ensure that each agent running on the host using the same build-path has a unique agent name.