Connect Bitbucket

1. 1

   Open Integrations

   In your workspace dashboard, open the Integrations tab. It lists your workspace connections: the identities Sarcio uses to open fix PRs, post the sarcio/approval build status, read Pipelines and dispatch remote builds. They belong to the workspace, not to a person. Connections are stored one per host and tokens are never shown again after you save them.

2. 2

   Create a repository access token (recommended)

   A repository access token acts as its own bot, not as a person, and reaches only the repository it was created in.

   • In the repository, open Repository settings → Security → Access tokens and press Create Repository Access Token.
   • Name: Sarcio. Pull requests and commits show the token's name, so name it Sarcio so they read clearly.
   • Scopes: Repositories Read and Write, and Pull requests Read and Write. Add Pipelines Read and Write only if the site uses remote builds.
   • Expiry: set one if your policy asks for it, and enter the same date in Sarcio so it can remind you to rotate it.

   Several repositories?

   A repository access token covers one repository, so create one per repository, or use a project or workspace access token with the same scopes. Project and workspace access tokens need Bitbucket Premium.
3. 3

   Save the token in Sarcio

   On the Integrations tab, under Add a bot or project access token (recommended), enter bitbucket.org, leave the provider on Auto-detect, paste the token and press Save token. Bitbucket has retired app passwords, so use an access token.

   When you save, Sarcio asks Bitbucket who the token belongs to (GET /2.0/user, an identity read that needs no extra scope). Repository, project and workspace access tokens can't call it, so a refusal there means Bot token. A token that answers belongs to a person and shows Personal. If Bitbucket can't be reached, the token still saves, badged Owner unknown.

   An Atlassian API token scoped to Bitbucket also works (choose Bitbucket as the app, and grant repository read, write and admin plus pull request read and write). It acts as the account that created it, so Sarcio's work appears as that person; prefer a repository access token. A token created for Jira doesn't authenticate Bitbucket.

   What Sarcio checks, and what the warnings mean

   Access tokens can't say who they are, so Sarcio checks them against the repositories your sites point at on bitbucket.org: it reads each repository (GET /2.0/repositories/{workspace}/{repo}) and lists one pull request, and reads the token's scopes from the x-oauth-scopes header Bitbucket returns. Anything missing shows as a warning on the connection; warnings never stop the save.

   • Missing repository:write or pullrequest:write scope. Sarcio can't push the fix branch or open the pull request. Access token scopes can't be edited, so create a new token with Repositories: Write and Pull requests: Write.
   • Missing pipeline:write scope (needed for remote builds). Shown only when a site on this host uses remote builds.
   • Can't read workspace/repo. The token belongs to a different repository, or the site's workspace ID and slug don't match. Create the token on that repository, or use a project or workspace access token.
   • Can't list pull requests. The token lacks Pull requests: Read.

   Bitbucket doesn't report when an access token expires, so the token form has an optional Token expires date. Enter the expiry you chose and workspace admins get an email 14 and 3 days before it, once per threshold, plus a chip on the connection. After fixing something in Bitbucket, press Re-check on the connection to run these checks on the stored token again.

4. 4

   Quick start: connect a personal account

   Trying Sarcio out? Under Quick start: connect a personal account, press Connect Bitbucket. Atlassian shows what Sarcio is asking for: read your account information and primary email, read and modify your pull requests, and read and modify your repositories. Press Accept.

   

   Enlarge

   It is quick, but it connects the workspace as you:

   • Pull requests, commits and build statuses appear as you.
   • Bitbucket's OAuth grant isn't limited to one repository. It covers every repository your account can reach, in every workspace.
   • The connection stops working if you leave or lose access.
   • The connection wears the Personal badge, with a warning banner on the Integrations tab.

   Back on Integrations, the bitbucket.org connection shows the account that approved it and the Personal badge. It replaces any token saved for the same host, and saving a token later replaces it.

5. 5

   Point the site at its repository

   For Bitbucket, the repo owner is the workspace ID and the repo name is the repository slug, both as they appear in the repository URL.

   On the Sites tab, press Manage next to the site and open Repository & source. Fill in the repository and the file a fix edits. What each field means.

   Repository & source

   Forge host          bitbucket.orgRepo owner          acmeRepo name           status-apiDefault branch      mainSource file         public/index.htmlServer source file  server.mjs

6. 6

   Approve a patch and get a pull request

   When a reviewer approves a patch and it goes live, Sarcio opens a pull request into the default branch. In the Meridian demo it opened about 25 seconds after approval. The description names who approved it and links to the report in Sarcio, and each commit gets one Approved-in-Sarcio-by: Ada L. trailer per approver. Approvers are named, never by email, and never added as Co-authored-by. An approver who linked their Bitbucket account (below) reads as @their-username in the description and the approval status. If an admin turns on acting links, an approver can also let Sarcio approve the pull request as them on patches they approve with Also act as me ticked (see acting links).

   

   Enlarge

   

   Enlarge

   Get @mentioned: link your Bitbucket account

   Any member can open Account and press Link Bitbucket, then Grant access. Bitbucket's consent screen lists repository and pull request access because it sets permissions per app, not per request. Linking reads only your account id, username, name and avatar, and Sarcio stores no token. What a link can and cannot do.

   

   Enlarge

   Require Sarcio's approval before merging

   The pull request's head commit carries a sarcio/approval build status: successful with the approvers' names and the risk rating (for example Approved in Sarcio by Ada L. and Bo K. · elevated risk), linking to the report, and failed if the live patch is retired or expires before the pull request merges. To make it a merge gate, open Repository settings → Branch restrictions (or merge checks on your plan), and require a minimum number of successful builds for the default branch that counts it alongside your Pipelines build.

   Sarcio also reads the pull request's build statuses (Bitbucket Pipelines included) while it is open, and shows the result as a Build: passing / failing / running chip next to the pull request on the report page and in Live patches.

   Show builds: Bitbucket Pipelines

   The build chip and the pull request's build count need a pipeline that runs on Sarcio's fix branches. Sarcio's branches start with sarcio/, so a branches: 'sarcio/**' pipeline in bitbucket-pipelines.yml builds each fix on push, and you can start it by hand from Pipelines → Run pipeline (Bitbucket can't start a pull-requests pipeline by hand). Enable Pipelines under Repository settings → Pipelines → Settings; the first time, Run initial pipeline lets you pick the fix branch and that pipeline.

   Enable Pipelines: two-step verification

   Bitbucket refuses to enable Pipelines with Two-step verification is required to enable Pipelines until the account turning it on has two-step verification, and that means two separate settings:

   • Atlassian account: id.atlassian.com → Security → Two-step verification. It asks for your Atlassian password. An account that signs in with Google has none: set one first through Can't log in? on the Atlassian sign-in page, which emails a recovery link.
   • Bitbucket: Personal settings → Security → Two-step verification. Scan the QR code, enter the code, then confirm from the email Bitbucket sends. Only after this does Enable Pipelines work.

   Changing the Atlassian password or two-step verification can invalidate a personal Connect Bitbucket connection (pull request sync then fails with 401 Token is invalid, expired, or not supported): press Connect Bitbucket again. A repository access token isn't affected.

   

   Enlarge

   

   Enlarge

7. 7

   If the pull request fails, retry it

   A failed pull request leaves the patch live and shows Retry pull request on the report page. Fix the credential, then retry. The Orphaned tab also offers Open pull request for live patches with no PR.

Troubleshooting

• 401 Unauthorized. The token expired or was revoked, a Jira-scoped Atlassian token was used, or the OAuth access was revoked in your Atlassian account. Save a Bitbucket access token or connect again, then Retry pull request.
• 403 or repository not found. The token lacks repository write or pull request write, belongs to a different repository, or the site's workspace ID and slug don't match the repository URL.
• The connection shows Personal or Owner unknown. Personal means the token belongs to a user account. Owner unknown means Sarcio couldn't ask Bitbucket when you saved; press Re-check on the connection.
• The connection shows warnings. See what the warnings mean, fix them in Bitbucket, then press Re-check.
• The consent screen mentions a missing privacy policy. If you host Sarcio yourself, add privacy policy and terms URLs to your Bitbucket OAuth client (Workspace settings → Apps and features → OAuth clients; Bitbucket used to call these consumers).
• After connecting you land on another dashboard address. Older deployments return from the provider to a shared dashboard address instead of your workspace. The connection is saved either way: go back to your workspace address (e.g. acme.sarcio.io) and it's listed on the Integrations tab.

Token scopes and OAuth scopes in detail: Repository access. To list pull requests on Jira tickets, see Bitbucket in Jira.