Skip to content

Git

Bitbucket

Report builds to Bitbucket Cloud pull requests as a commit status and a summary comment.

The Bitbucket integration supports Bitbucket Cloud. Each build of a linked project shows on the pull request as a commit status named CirCI / <build name>, and CirCI keeps one summary comment on the pull request up to date. It's the smallest of the three git integrations: statuses and comments, with commands, but no buttons.

You get Where
A commit status per build name The pull request's builds section
One summary comment per pull request The pull request's activity
/circi approve, /circi reject, /circi rerun A comment on the pull request
One help comment, which also holds each command's answer The same activity, edited in place

An owner or admin of the CirCI workspace opens Workspace settings › Integrations › Add integration › Bitbucket.

  1. In Bitbucket, create a Bitbucket workspace or repository access token that can read and write pull requests. An app password also works.
  2. In CirCI, enter the Bitbucket workspace ID (acme in bitbucket.org/acme; lower case letters, digits, dashes and underscores) and the Access token. For an app password, also enter the Username it belongs to.
  3. Connect. CirCI lists the Bitbucket workspace's repositories with the token, so a rejected token, a token that can't read the workspace, or an unknown workspace fails here with a message.
  4. Add the webhook on Bitbucket (below).
  5. On the integration's page, choose the repository each CirCI project reports to, written workspace/repository (for example acme/web).
  6. To block merging, add a merge check in Bitbucket that requires the build status to pass.

A connection is one Bitbucket workspace, and a Bitbucket workspace can be connected to one CirCI workspace only. Connecting again with a new token replaces the credentials and clears a "needs attention" flag.

On the Bitbucket integration's page, owners and admins see the webhook address and the secret. In each Bitbucket repository open Repository settings › Webhooks and add:

  • URL: PUBLIC_URL/webhooks/bitbucket (the alias PUBLIC_URL/api/integrations/bitbucket/webhook also works).
  • Secret: the secret shown on the integration's page. It's derived from the instance secret.
  • Triggers: pull request created, updated, and comment created.

CirCI checks the X-Hub-Signature header on every delivery.

One per build name, so each build name keeps its own status. It links to the build, and its description is the same title the GitHub check uses.

Situation Status
Processing INPROGRESS
No changes, approved, or the project doesn't block merging SUCCESSFUL
Changes await review and merging is blocked, or rejected FAILED
Some screenshots couldn't be read (1 screenshot couldn't be read) FAILED when the project blocks merging, SUCCESSFUL otherwise, until the build is uploaded again

One comment per pull request, edited in place, with the same text as the GitHub summary comment: a table of builds and any hosted sites for the newest commit. A build with screenshots that couldn't be read says "1 screenshot couldn't be read" in its review cell.

Comment /circi approve, /circi reject or /circi rerun on a line of its own. Bitbucket has no reactions, so CirCI always answers in its one help comment per pull request, edited in place with the latest answer:

  • When it acted: "Done: approved the latest CirCI build" (or "rejected", or "rerunning the latest CirCI builds").
  • When it didn't: the reason from the GitHub page: no build yet, still processing, processing failed, or nothing to decide.
  • When it can't match you to an account: "I couldn't tell who you are in CirCI. Link your Bitbucket account to a CirCI account that belongs to this project's workspace (PUBLIC_URL), then try again."

The Merge gate settings on the CirCI project page apply as they do for GitHub: Unreviewed changes block merging, Flaky-only changes block merging and Approve default-branch builds automatically. A build with screenshots that couldn't be read follows Unreviewed changes block merging too: it fails when that is on and passes, with the count in the description, when it's off.

Who blocks the merge, Bitbucket's status or the CI job, is explained in How a build flows. On an instance without the GitHub App configured, the server doesn't know a Bitbucket-linked project reports to a git host, so pass --gate status to make Bitbucket's status the gate.

What you see Why, and what to do
Connect fails with a message The token was rejected, can't read the Bitbucket workspace, or the workspace ID is wrong. For an app password, check the Username too
Statuses appear but no comment The webhook isn't added, or its secret doesn't match. Check the webhook's request log in Bitbucket
Every command gets the "couldn't tell who you are" answer Expected today: see the caution above. Review in the dashboard
The integration shows needs attention Bitbucket rejected the token. Connect again with a new token
  • Pull request created or updated: remembers the author, and gives builds their pull request number by matching the source commit or branch.
  • Comment created on a pull request: the /circi commands.

Nothing happens when a pull request is merged or declined.

  • Approve and Reject buttons (Bitbucket statuses have none).
  • Bitbucket Server and Data Center. Only Bitbucket Cloud is supported.

Not yet verified against bitbucket.org.