Buildkite Agent v4 becomes the stable release on 1 September 2026

On 1 September 2026 (AEST), Buildkite Agent v4 becomes the stable release. From that date, installations and upgrades that follow the latest or stable release channels will use v4.

We expect most customers to be unaffected. v4 retires functionality that has been deprecated for years and makes current, supported behaviour the default, giving the agent a cleaner baseline for what we build next. New capabilities have continued shipping in v3, so for most setups the move to v4 changes nothing about how you use the agent.

You can test v4 in beta today to confirm your setup is ready before the switch. The v3 → v4 upgrade guide covers every change, with instructions for testing, planning your upgrade, or staying on v3 if you need more time.

What might affect you

• Secrets in pipeline uploads now fail the upload. Detected secrets cause pipeline upload to fail by default. Use --allow-secrets to opt out while you update your pipeline.
• post-checkout, post-command, and pre-exit hooks now run in reverse order. In v3, agent, repository, and plugin hooks run in the same order for every phase. In v4, these three run in reverse: the last configured plugin runs first, followed by earlier plugins, repository hooks, then agent hooks. This lets cleanup unwind setup in the opposite order, but may affect hooks that depend on the current sequence. The legacy-post-hook-order experiment temporarily restores the v3 order.
• Agent configuration variables propagate into child environments. propagate-agent-config-vars is now the default, so configuration such as BUILDKITE_GIT_* and BUILDKITE_SHELL passes into containers and other child processes. These variables appear in BUILDKITE_ENV_FILE as bare names rather than KEY=value entries — update any custom hooks or tools that parse every line as an assignment.
• OpenTracing is removed in favour of OpenTelemetry. v4 removes the agent's built-in Datadog APM tracing backend and its direct DogStatsD metrics integration. To keep sending traces to Datadog, enable OpenTelemetry with --opentelemetry-tracing (or BUILDKITE_OPENTELEMETRY_TRACING) and configure the Datadog Agent or another OpenTelemetry Collector to receive OTLP traces. For metrics, enable --opentelemetry-metrics (or BUILDKITE_OPENTELEMETRY_METRICS) and send them to the same collector, or scrape the agent's Prometheus endpoint with Datadog's OpenMetrics integration.
• Some configuration options are renamed or removed. Several have been deprecated for years: --meta-data was replaced by --tags in 2017 and has worked as an alias ever since. Others change in v4 itself — --cancel-grace-period and --signal-grace-period-seconds are replaced by --cancel-signal-timeout and --cancel-cleanup-timeout. The upgrade guide lists every one.
• The legacy Docker integration is removed. v4 removes the integration configured through BUILDKITE_DOCKER and BUILDKITE_DOCKER_COMPOSE_CONTAINER. If you use it, switch to the docker or docker-compose plugins, which are unaffected.

The upgrade guide has the complete list and the migration steps for each change.

What to do before 1 September

• Review the upgrade guide to check whether any change affects your agent configuration, hooks, plugins, or observability setup.
• Test v4. Install the beta and run representative jobs. The upgrade guide includes instructions for common installation methods.
• Decide how you'll receive v4. Agent installations that follow latest or stable will move to v4 on 1 September. If you pin the agent version, update the pin when you're ready.
• Need more time? Stay on v3 by switching to the oldstable release channel or setting the agent version to 3, depending on your installation method. v3 will continue to receive critical security and reliability fixes, and we'll announce an end-of-support date with plenty of notice.

Hosted Agents

If you use Hosted Agents, there is nothing to configure. Buildkite will manage the move to v4 over the weeks leading up to 1 September, and the agent version your Hosted Agents use will update automatically. We'll monitor the rollout closely and work directly with anyone who needs more time or hits a compatibility issue.

Questions or need a hand? Reach out to support@buildkite.com or your account team.