Bitbucket Cloud · Pipelines · Checked October 31, 2026

Bitbucket Pipelines: rerunning a failed pipeline

When a pipeline fails, Bitbucket's Rerun button offers two things: run only the failed steps again, or run the entire pipeline again. Neither is in the REST API, so from a script or another tool the only way is to start a new pipeline on the same commit. Bitbucket has no setting to retry a failed step by itself.

Rerun on Bitbucket

From Atlassian's View your pipeline: open the failed pipeline and choose Rerun.

• Rerun failed steps runs only the failed steps again, in the same pipeline. Its log gets the new run, and the Runs menu in the pipeline's log lets you pick each run.
• Rerun entire pipeline starts a new pipeline, with a new number and its own log.
• Build minutes add up: hover over a step's duration to see the total of all its runs.
• Build artifacts are kept for 14 days, so a step that uses artifacts from an earlier step can only be rerun within 14 days.

There is no rerun in the API

Bitbucket's Pipelines API can start a pipeline, read pipelines, steps, logs and test reports, and stop a pipeline (stopPipeline), and that is all. Rerunning is asked for in BCLOUD-21591 "API to rerun pipeline build", both the entire pipeline and only the failed steps: opened in January 2022, still Gathering Interest, 18 votes, the latest on October 27, 2026. Its copy for the entire pipeline, BCLOUD-21608, was closed as Won't Fix in January 2024 for lack of activity.

So a script reruns by starting a new pipeline on the same target. Read the failed pipeline first:

curl -u '<email>:<API token>' \
  https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO/pipelines/{PIPELINE_UUID}

Its target has the branch (ref_name), the commit and the selector, the part of bitbucket-pipelines.yml that ran. Send them back to Run a pipeline:

curl -X POST -u '<email>:<API token>' \
  -H 'Content-Type: application/json' \
  https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO/pipelines/ \
  -d '{
    "target": {
      "type": "pipeline_ref_target",
      "ref_type": "branch",
      "ref_name": "main",
      "commit": { "type": "commit", "hash": "<the same commit>" },
      "selector": { "type": "branches", "pattern": "main" }
    }
  }'

• Every step runs again, and the pipeline gets a new number, as with Rerun entire pipeline.
• A custom pipeline needs its variables sent again (run a custom pipeline with variables). Bitbucket does not hand back the value of a secured one.
• A pull request pipeline uses "type": "pipeline_pullrequest_target" with the source and destination branches, both commits and the pull request's id, as in the API reference's example.
• The API token needs the write:pipeline scope.

Retry automatically

Bitbucket Cloud "does not have a feature to automatically re-run a failed build", says Atlassian's knowledge base article (updated September 2025). Its workaround: in the step's after-script, look at BITBUCKET_EXIT_CODE, and when it is not 0, start the pipeline again with the atlassian/trigger-pipeline pipe.

• The pipe starts the branch's pipeline again, from the beginning, not the step that failed. It does not wait for it to finish.
• Its API token needs the scopes read:pipeline:bitbucket, write:pipeline:bitbucket and read:repository:bitbucket.
• Atlassian warns that a step that keeps failing keeps starting new pipelines, until someone stops them on Bitbucket.
• A retry option for the pipe itself is asked for in BCLOUD-22872 (Gathering Interest since 2023).

Run pipelines again from IntelliJ IDEA

Pipeline Inbox for Bitbucket Pipelines, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pipelines of all your Bitbucket Cloud repositories in an IDE tool window, numbered like Bitbucket (#42 (2) once its failed steps were rerun). Its Run Again starts a new pipeline on the same commit, branch or pull request with the same part of bitbucket-pipelines.yml, the same request as above. A pipeline whose variables Bitbucket does not hand back, such as a secured one, opens Run Pipeline… instead, to fill them in. Only the failed steps cannot be rerun from the IDE, as the API has no way to: use Bitbucket's Rerun for that. The list, steps and logs are free; running, running again and stopping are Pro (US$1.50 a month, with a 30-day trial).

Get it on JetBrains Marketplace

Atlassian, Bitbucket and Bitbucket Pipelines are trademarks of Atlassian; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.

More: Run a custom pipeline with variables · The build passed before and fails now · The artifact is missing in the next step · Out of build minutes · "Permission denied to update branch" · "You have reached your pull rate limit" (Docker Hub) · "There is an error in your bitbucket-pipelines.yml" · "This pipeline was paused" (deployments) · Bitbucket Pipelines plugins for IntelliJ IDEA compared · 日本語