Connecting Bitbucket Cloud
A Bitbucket connection is your Atlassian account email plus an API token with Bitbucket scopes. Deckgauge finds your workspace from the token, lets you pick repositories grouped by Bitbucket project, and syncs pull requests, approvals, commits and Pipelines deployments into engineering intelligence. Tasks stay in Jira — Bitbucket pull requests link back to them by issue key, using the keys of the Jira projects attached to the same board.
BBBitbucket
Creating a Bitbucket connection — the workspace is detected from the token.
| Field | Value |
|---|---|
| The Atlassian account the token belongs to | |
| API token | Created with Create API token with scopes, app Bitbucket; sent as HTTP Basic auth and stored encrypted |
| Workspace | Optional — detected automatically when the token sees one workspace, chosen from a list when it sees several |
How to connect Bitbucket
- Open Atlassian API tokens and click Create API token with scopes — not the plain Create API token.
- Name it
Deckgauge, set an expiry, and choose Bitbucket as the app. - Tick the read scopes:
read:user:bitbucket,read:workspace:bitbucket,read:project:bitbucket,read:repository:bitbucket,read:pullrequest:bitbucket,read:pipeline:bitbucket. - Add source → Bitbucket, enter your email, paste the token and click Create & test.
- Pick repositories. They are grouped by Bitbucket project — Select all on a project attaches every repository in it at once.
“API Token provided has no Bitbucket scopes”This is the most common mistake: a plain Atlassian API token (the kind Jira uses) authenticates, but Bitbucket refuses it. Create a new token with Create API token with scopes and pick Bitbucket. App passwords are retired by Atlassian and are not supported.
What syncs
| Data | Window on first sync | Used by |
|---|---|---|
| Pull requests, with line counts and Jira keys from title, description and branch | 180 days | PR throughput, cycle time, review metrics, ticket timelines |
| Approvals and comments | with each PR | Review mix, reviewer participation, review quality |
| Commits on the main branch | 180 days | Commits per developer, developer heatmap, lead time |
| Pipelines deployments | 90 days | DORA deployment frequency, change failure rate, lead time |
After the first sync, each repository resumes from where the previous sync stopped. Bitbucket never adds rows to a board — that is what your Jira source is for.
How delivery is counted
- Release PRs are not counted twice. A pull request whose source branch is itself a long-lived branch —
stage,staging,develop,main,master,prod, or arelease…branch — is a release, not new work. It is stored but left out of PR throughput and review metrics. Ahotfix/…branch merged straight into production is normal work. - A deployment is a pipeline, not an environment. One pipeline that deploys to several environments of type Production (one per brand or region, say) counts as one deployment. Staging and Test environments never count.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| “This is a plain Atlassian API token” | Token created without Bitbucket scopes | Create one with Create API token with scopes → Bitbucket |
| Repositories missing from the picker | The account can't read them, or the scope read:repository:bitbucket is missing | Grant access in Bitbucket, or recreate the token with every scope above |
| Deployment frequency is zero | Pipelines don't deploy to an environment of type Production, or read:pipeline:bitbucket is missing | Set the environment type in Repository settings → Deployments |
| PRs don't link to Jira tickets | The board has no Jira project attached and no ticket key prefixes | Attach the team's Jira project to the same board — its key (e.g. RND) is used automatically — or add the key to the board's ticket prefixes |
Related
- Connecting Jira — where the tasks live.
- When your data refreshes — scheduled and manual sync.
- When a connection breaks — expired tokens and reconnecting.
Last updated