How to Set a Build Status on a Commit in Bitbucket Pipelines

Post a custom build status to a commit via the Bitbucket build-status API so an external check shows on the PR.

Use the per-step BITBUCKET_ACCESS_TOKEN (OAuth) to POST to the commit build-status endpoint. The status appears on the commit and pull request with your key and state.

Post a build status

The injected access token authenticates the API call; key is the unique status name.

image: curlimages/curl:8.8.0

pipelines:
  default:
    - step:
        name: External gate
        oidc: false
        script:
          - |
            curl -sS -X POST \
              -H "Authorization: Bearer ${BITBUCKET_ACCESS_TOKEN}" \
              -H "Content-Type: application/json" \
              "https://api.bitbucket.org/2.0/repositories/${BITBUCKET_WORKSPACE}/${BITBUCKET_REPO_SLUG}/commit/${BITBUCKET_COMMIT}/statuses/build" \
              -d '{"key":"perf-budget","state":"SUCCESSFUL","name":"Perf budget","url":"https://ci.example.com"}'

Gotchas

• BITBUCKET_ACCESS_TOKEN is a short-lived per-step OAuth token; it is available without storing a credential.
• state must be SUCCESSFUL, FAILED, INPROGRESS, or STOPPED; key must be unique per check.
• Posting the same key again updates that status rather than creating a duplicate.

Related guides