v4.0.0

Buildkite Agent v4.0.0

Buildkite Agent v4 is now stable. Most features and fixes developed since v3 and v4 diverged were backported to v3, so this changelog focuses on behaviour that differs from v3.

Review the v3 to v4 upgrade guide before upgrading.

Important

v4 removes a number of deprecated flags, environment variables, configuration options, and experiments. Removed flags fail loudly; removed environment variables and configuration options fail silently. See Removed flags, environment variables, and configuration options at the end of the breaking changes below, and the v3 to v4 upgrade guide for the full list.

Breaking changes

Job handling

• Removed the deprecated built-in Docker integration. The docker and docker-compose plugins remain supported.
• Cancelled Windows jobs now return exit status 1 instead of 0.
• Replaced cancel-grace-period and signal-grace-period-seconds with cancel-signal-timeout and cancel-cleanup-timeout, defaulting to 10 and 5 seconds respectively.

Job logs

The agent now always emits ANSI timestamp codes. Plaintext timestamps and the option to disable ANSI timestamps have been removed.

Checkout

• BUILDKITE_COMMIT is resolved to a commit hash after checkout.
• Replaced built-in SSH key scanning and known-hosts management with OpenSSH host-key-checking options.
• Git commit verification now defaults to strict and accepts only strict or off. Replace previous empty or warn values before upgrading.

Agent parallelism

spawn-with-priority now accepts static, ascending, or descending. Boolean values are no longer accepted, and passing one prevents the agent from starting.

Observability

• Removed OpenTracing, direct DogStatsD support, and Datadog-specific tracing workarounds. Use OpenTelemetry instead.
• Renamed tracing-service-name to telemetry-service-name.
• Trace-parent propagation is now always enabled.
• Replaced jobs.success and jobs.failed with jobs.finished.
• Replaced jobs.duration.success and jobs.duration.error with jobs.duration.
• Use the exit_code attribute to distinguish successful and failed jobs.
• The standard Prometheus job metrics now include priority and queue labels, replacing the separate _with_labels_total metrics.

Pipeline uploads

• Removed the --reject-secrets flag (BUILDKITE_AGENT_PIPELINE_UPLOAD_REJECT_SECRETS). Rejecting secrets is now the default, so the flag is redundant — but buildkite-agent pipeline upload --reject-secrets no longer runs. It exits immediately with fatal: flag provided but not defined: -reject-secrets. Remove the flag before upgrading, including from any wrapper scripts, plugins, or tooling that shells out to pipeline upload.
• Pipeline uploads now reject interpolated secrets by default. To permit them, use --allow-secrets (BUILDKITE_AGENT_PIPELINE_UPLOAD_ALLOW_SECRETS).
• Secret detection now includes trigger-step build.env values.

Artifacts

• Windows artifact paths are now stored with / separators.
• Removed artifact upload --follow-symlinks; use --glob-resolve-follow-symlinks.
• Artifact downloads now unconditionally prevent path traversal.

Plugins and hooks

• Removed deprecated plugin configuration environment-variable aliases that collapsed consecutive underscores.
• post-checkout, post-command, and pre-exit hooks now run in reverse setup order: plugins last-to-first, repository, then agent.
• Enable the legacy-post-hook-order experiment to temporarily restore v3 ordering.

Command behaviour

• oidc request-token now exits with status 77 for definitive API refusals using HTTP status 400, 401, 403, 404, 410, or 422. Other failures continue to exit with status 1.

Removed flags, environment variables, and configuration options

v4 removes a number of deprecated flags, environment variables, agent configuration options, and experiments. The upgrade guide lists all of them with their replacements.

How they fail depends on how you set them:

• Flags fail loudly. buildkite-agent exits immediately with fatal: flag provided but not defined, before running any work. A single stale flag in a pipeline or hook breaks the build on the first command.
• Environment variables and agent configuration file options fail silently. The agent starts normally and the setting is ignored, so behaviour changes with no error and no warning.

Before upgrading, check the guide's list against your pipelines, hooks, plugins, agent configuration files, and any tooling that shells out to buildkite-agent.

Other changes

• Added Linux systemd watchdog support based on successful Buildkite heartbeat activity.
• Added an Ubuntu 26.04 agent Docker image.

New Contributors

• @JoeColeman95 made their first contribution in #4232
• @Temikus made their first contribution in #4239

Full Changelog: v3.136.0...v4.0.0