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 |
Set up
Section titled “Set up”An owner or admin of the CirCI workspace opens Workspace settings › Integrations › Add integration › Bitbucket.
- In Bitbucket, create a Bitbucket workspace or repository access token that can read and write pull requests. An app password also works.
- In CirCI, enter the Bitbucket workspace ID (
acmeinbitbucket.org/acme; lower case letters, digits, dashes and underscores) and the Access token. For an app password, also enter the Username it belongs to. - 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.
- Add the webhook on Bitbucket (below).
- On the integration's page, choose the repository each CirCI project reports to, written
workspace/repository(for exampleacme/web). - 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.
Add the webhook on Bitbucket
Section titled “Add the webhook on Bitbucket”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 aliasPUBLIC_URL/api/integrations/bitbucket/webhookalso 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.
What appears where
Section titled “What appears where”The commit status
Section titled “The commit status”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 |
The summary comment
Section titled “The summary comment”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.
Commands
Section titled “Commands”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."
Settings
Section titled “Settings”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.
The merge gate in CI
Section titled “The merge gate in CI”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.
Troubleshooting
Section titled “Troubleshooting”| 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 |
What the webhook handles
Section titled “What the webhook handles”- 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
/circicommands.
Nothing happens when a pull request is merged or declined.
Not supported yet
Section titled “Not supported yet”- Approve and Reject buttons (Bitbucket statuses have none).
- Bitbucket Server and Data Center. Only Bitbucket Cloud is supported.
Not yet verified against bitbucket.org.