Canceling builds

Buildkite Pipelines provides several ways to cancel builds and jobs, either automatically or manually.

Cancel running intermediate builds

Sometimes you may push several commits in quick succession, leading to Buildkite Pipelines building each commit in turn. You can configure your pipeline to cancel these running builds and only build the latest commit.

To cancel running builds on the same branch:

  1. Navigate to your pipeline's Settings.
  2. Select Builds.
  3. Select Cancel Intermediate Builds.
  4. (Optional) Limit which branches build canceling applies to by adding branch names in the text box below Cancel Intermediate Builds. For example, branch-one means Buildkite Pipelines only cancels intermediate builds on branch-one. You can also use not-equals: !main cancels intermediate builds on all branches except main.

You can also configure these options using the REST API.

Using Cancel Intermediate Builds and re-running earlier builds

If an earlier build has started running again (for example, due to a job being retried) while the newest build is already running, then this earlier build will not be canceled.

If, however, an earlier build has started running again before a new build starts running, then the earlier build will be canceled.

Manually cancel a job

If your pipeline has multiple command steps, you can manually cancel a step, which will cause the build to fail.

If you do not want the build to fail when you cancel a specific step, you can set soft_fail.

To manually cancel a job:

  1. From your Buildkite dashboard, select your pipeline.
  2. Select the running build.
  3. Select the job (step) you want to cancel.
  4. Select Cancel.

Cancel a build using the agent CLI

You can cancel a build using the buildkite-agent build cancel command. This is a job-level command, meaning it runs within the context of a job and authenticates using the $BUILDKITE_AGENT_ACCESS_TOKEN environment variable that Buildkite Pipeline automatically provides to every running job—on both self-hosted and Buildkite hosted agents.

buildkite-agent build cancel

This cancels the build associated with the current job's context. You can also target a specific build using the --build flag with the build UUID, or by setting the $BUILDKITE_BUILD_ID environment variable.

This command is typically called from within a pipeline step script. If you are using Buildkite hosted agents, you can also run the command interactively from a terminal session open on a running job. This is a separate browser-based feature for investigating the job environment.