How to Retry a Failing Step in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

Bitbucket has no per-step auto-retry keyword - rerun failed steps from the UI or script a retry loop.

For transient failures, rerun failed steps from the pipeline view, or wrap a flaky command in a bash retry loop with backoff so the step recovers automatically.

Script-level retry with backoff

This loop retries the command up to three times with increasing backoff before failing the step.

bitbucket-pipelines.yml

pipelines:
  default:
    - step:
        name: Smoke test
        image: curlimages/curl:8
        script:
          - |
            for i in 1 2 3; do
              curl -fsS https://api.example.com/health && exit 0
              echo "attempt $i failed; retrying"
              sleep $((i * 5))
            done
            exit 1

Gotchas

Bitbucket has no retry: keyword - automatic retry must be scripted in the step or done by rerunning from the UI.
Rerunning failed steps restarts from the failed step using the prior steps' artifacts, not from scratch.
Only retry transient/infra commands in the loop; do not loop test suites and hide real failures.

Frequently asked questions

How do I retry a Failing Step in Bitbucket Pipelines?

For transient failures, rerun failed steps from the pipeline view, or wrap a flaky command in a bash retry loop with backoff so the step recovers automatically.

Script-level retry with backoff?

This loop retries the command up to three times with increasing backoff before failing the step.

References

GitHub Actions documentation