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.

The Flaky Resolution feature is being deprecated and will be removed for all users in the coming week.

You can continue managing flaky tests by removing the flaky label. You can review all currently flaky tests via the Tests page, by filtering for tests with the flaky label.

Learn more about flaky test management.

The My Assignments feature is being deprecated and will be removed for all users in the coming week.

Users can continue to review tests owned by their teams using the filtering functionality on the Tests and Flaky tests pages.

As part of this change, the Flaky Summary Mailer will also be updated to show the flakiest tests owned by your team, rather than those that were previously assigned.

To enhance the overall reliability and scalability, we are implementing changes to how Buildkite handles API GET requests that include a body in the payload starting September 18th.

As a result of these changes, any GET request to api.buildkite.com that includes a body will receive a 403 status (Forbidden) as a response.

This may impact legacy clients, particularly older versions of Buildkite's Terraform provider (< 0.15). To ensure compatibility, we recommend upgrading to the latest version of our Terraform provider.

During the week commencing August 28th, Buildkite will intermittently enable this change for short periods as a low-impact method of uncovering issues.

We value our customers and their experience with Buildkite, so we will directly communicate with any customers continuing to submit API GET requests with a body.

Thank you for your understanding and cooperation as we continue to improve our platform.

Update: We originally advised this change would occur on August 14th, we have delayed this change to September 18th.

On 13 July 2023, there will be some deprecations in the GraphQL API. The following objects from the pipeline will be deprecated: buildRetentionEnabled, buildRetentionNumber, and buildRetentionPeriod.

To get more information about the pipeline schema and its changes, please refer to the documentation.

At Buildkite we take your security seriously, because of that starting 22 June 2023 you will not be able to retrieve agent tokens for clustered and unclustered agents through the token attribute after it has been created through GraphQL APIs.

Read more about how to create Agent Tokens

Read more about how to create Cluster Agent Tokens

Update: The date for deprecation will be delayed to 4 July 2023 due to the breaking change introduced to Buildkite terraform provider. If you are a customer using the Terraform provider, please make sure to upgrade to version 0.19.0 beforehand.

Using %n in agent names is deprecated and will soon be removed 👋

The default name for a Buildkite Agent used to be agent-%n, resulting in agent-1, agent-2, etc. Pretty quickly, though, this gets tricky to keep unique, especially with a big database full of agent names. So to keep our database humming, we're removing support for %n.

We began this process with Buildkite Agent v3.27.0 released on 8th February, 2021, removing %n from the default agent name. Elastic CI Stack for AWS v5.2.0 was also updated to replace usage of %n with %spawn on the same day.

If you're using Elastic CI Stack for AWS, please make sure you're running v5.2.0 or newer. The version you're using should be visible on your agents page:

If you're running your agents another way, please review your agent configuration and confirm you're not using %n.

If you are using %n, there are a few alternatives:

• If you're running a single agent on each host, use %hostname.
• If you're running multiple agents, use the spawn option and %hostname-%spawn.
• If neither of the previous options work, use %random which will turn into a few random characters.

Check out our docs for a complete reference: https://buildkite.com/docs/agent/v3/configuration#name

We'll begin brownouts of %n on Monday, 8th August 2022. Finally, we'll remove support for %n on Monday, 5th September 2022. Agents which still use %n in their name after this date will fail to connect and accept work.

If you need some more time, or have a problem completing this migration, please drop us an email to support@buildkite.com.

In November 2018, we posted a changelog deprecating BUILDBOX_* environment variables from generating for new jobs.

From today, we no longer send BUILDBOX_* environment variables.

You can see our environment variable documentation for a complete list of current job environment variables.

To simplify querying jobs with GraphQL we're shipping a fix to make sure broken jobs return a "BROKEN" state 🚦

Starting on Tuesday, 1st June 2021 at 00:00 UTC broken jobs fetched via the GraphQL API will return BROKEN instead of SKIPPED.

If you have scripts or other clients of the GraphQL API that rely on jobs returning a SKIPPED state then you will need to update these to accept the BROKEN state as well.

When fetching jobs from our REST API, broken jobs already return a state of BROKEN and will continue to do so.

If you need this switch made for your organization prior to 1st June 2021, please reach out to support@buildkite.com 👋🏻

We're discontinuing support for TLS 1.0 and 1.1 as part of regular efforts to improve the security of the Buildkite platform. We're making this change on agent.buildkite.com effective immediately. As of 1st March, 2020 we will only support TLS 1.2 and above on buildkite.com and all subdomains.

These older protocols have been on a deprecation track for quite a while. Almost all traffic to buildkite.com is already using TLS 1.2. It has been supported in browsers since 2013, and many browsers will be removing support for TLS 1.0 and 1.1 this year. TLS 1.2 has been supported by the Buildkite Agent since the first v2 release in 2015. If you're also using the Buildkite API please double check that your clients support TLS 1.2.

If you have any questions or concerns please reach out via support@buildkite.com.

The Artifacts API will no longer return the glob_path and original_path fields from 1st September 2019.

When uploading artifacts the Buildkite Agent currently submits information about the glob pattern used to match the artifacts, and where on the filesystem each artifact was stored. We will remove the glob_path and original_path fields from artifacts to reduce the amount of your data we store.

The only place exposing these fields is in the REST API when listing artifacts or retrieving an individual artifact with the Artifacts API. They are not used again by the Buildkite Agent once the artifact is uploaded.

If you rely on this data, please reach out via support@buildkite.com.

Some of you may not know this, but Buildkite actually used to be called Buildbox! We changed our name back in December 2014.

From today, BUILDBOX_* environment variables won't be generated for new jobs.

We've confirmed there are no agents running this version connected to Buildkite, however we can't tell if you're referencing any BUILDBOX_* environment variables in your build scripts. If you are, please update them to use their BUILDKITE_* equivalent.

You can see our environment variable documentation for a full list of current job environment variables.