Connect Bitbucket with an Atlassian API token

Bind Bitbucket to Expecto Centum so the Publish stage can push commits and open pull requests on your behalf — an Atlassian API token, scoped narrowly to the seven Bitbucket permissions the pipeline actually needs.

Bitbucket Cloud authenticates with an Atlassian API token. Tokens authenticate as HTTP Basic with your Atlassian email as the username and the token as the password; the desktop app combines the two on every request. The token inherits your Bitbucket permissions exactly, so whatever your user can do in the browser, the pipeline can do through the token.

Bitbucket uses Atlassian's API token with scopes wizard. The scopes are granular and don't imply each other — every one of the seven the pipeline needs has to be ticked individually. The resulting token is encrypted and stored on this device; nothing leaves the machine.

Step I Open the Atlassian API tokens page

Sign in to your Atlassian account and open the API tokens page at id.atlassian.com/manage-profile/security/api-tokens. The page lists any existing tokens and exposes two creation buttons in the top right.

You can also reach it from your Atlassian avatar → Manage account → Security → Create and manage API tokens.

✦✦✦✦

Step II Create the token with scopes

The wizard walks you through four panes — Name and expiry, Select app, Select scopes, and Create token. Fill them in order.

On Name and expiry:

1. Name — something you'll recognize later. We suggest Expecto Centum · {machine name} (e.g. Expecto Centum · mbp-m4) so you can tell which device owns the token when revoking.
2. Expires on — pick a date up to 365 days out (Atlassian's hard ceiling). Tokens can't be renewed in place; when this date hits, you'll repeat Steps I–III and revoke the old one.
3. Click Continue.

✦✦✦✦

On Select app:

1. Select API token app — choose Bitbucket. Each token can only access one Atlassian product, so a Bitbucket token won't talk to Jira and vice versa.
2. Click Continue.

✦✦✦✦

On Select scopes, tick exactly these seven. Atlassian's scopes don't imply each other, so each one has to be selected individually — start with the admin scope and the four read scopes:

• admin:repository:bitbucket — create a new repo when you pick Create new repo instead of an existing one; Bitbucket refuses to create a repo without it, even with the write scope granted.
• read:pullrequest:bitbucket — find open PRs and read merge state for the Reaper stage.
• read:repository:bitbucket — list and clone repos.
• read:user:bitbucket — used by the initial reachability check (GET /2.0/user); without it the token verifies as 403 even when every other scope is fine.
• read:workspace:bitbucket — find your workspaces, to list their repos and to choose where a new repo goes: the first workspace you administer, or the first you belong to when you administer none.

✦✦✦✦

Then the two write scopes:

• write:pullrequest:bitbucket — open the PR for each ticket.
• write:repository:bitbucket — push commits.

None of the other 38 scopes are required. Click Continue.

✦✦✦✦

On Create token, review the summary. The Admin section should list one scope, the Read section four and the Write section two — if anything is missing, hit Back rather than Create token, because the token can't be edited after creation. When everything matches, click Create token.

✦✦✦✦

Step III Copy the token

Atlassian shows the token value once on the Create token pane. Click Copy and keep the window open until you've pasted it into Expecto Centum — the token starts with ATATT and runs about 192 characters.

✦✦✦✦

Step IV Paste into Expecto Centum

In the desktop app, open Config (the gear in the top-right of the dashboard) and select the Connections tab. Under Git provider connections, click Add Bitbucket. The dialog asks for:

• Label — how this connection appears in the Connections list (e.g. Bitbucket (work)). Also used to derive the connection's stable id.
• Host — https://bitbucket.org.
• Atlassian email — the email registered on the Atlassian account that minted the token. Bitbucket's API uses Basic auth, so the email pairs with the token on every request.
• API token — paste the value you copied in Step III. Input is password-masked; the value is never logged.

Click Save. Expecto Centum immediately probes Bitbucket with the credentials — a bad token, wrong email, or unreachable host rejects the add up front with a specific error (no half-registered connection lands on disk). On success, the token is encrypted and written to a machine-bound file alongside the app data, and the new row appears in the Connections list showing your Bitbucket username, the host, and a trash icon.

Step V Verify the connection

There's no separate verify step — the probe runs as part of Save, so a row appearing in the Connections list is the verification. The subtitle shows the authenticated Bitbucket username and host; if either looks wrong, trash the row and re-add with the correct email or host.

When you run a pipeline that publishes to a Bitbucket repo, the Publish stage resolves the connection bound to that repo and uses the stored token to push + open the PR. The repo → connection binding is set in Config → Context when you add the repo.

Step VI Rotating or revoking the token

Rotate before the expiry date, and immediately if a machine is lost or a teammate leaves. Atlassian doesn't renew tokens in place — rotating means minting a new one and discarding the old.

• To rotate: mint a new token (Steps I–III) with a fresh name, trash the existing Bitbucket connection in the Connections tab (removes the encrypted token locally), then click Add Bitbucket and paste the new value. Finally, revoke the old token on the Atlassian API tokens page so it's invalidated server-side.
• To revoke: open the Atlassian API tokens page, find the token by its name, and click Revoke. Then trash the connection in Expecto Centum so the stale entry is purged locally.

✦ Troubleshooting