Upcoming change to the Buildkite API

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 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.



GraphQL Build Retention Objects Deprecation

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.



Agent Token being Deprecated from GraphQL APIs

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.



Agent names no longer support "%n"

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:

List of buildkite agents with buildkite-aws-stack tag indicating version v5.9.0)

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:

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



BUILDBOX_* environment variables removed from Buildkite

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.



GraphQL API state change for broken jobs

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 👋🏻



Discontinuing support for TLS 1.0 and 1.1 🔒

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 effective immediately. As of 1st March, 2020 we will only support TLS 1.2 and above on and all subdomains.

These older protocols have been on a deprecation track for quite a while. Almost all traffic to 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



Artifacts glob_path and original_path fields are deprecated

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.

Diff showing the fields removed from a "Get Artifact" JSON response

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



Agents prior to 2.0 are no longer supported

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.