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.

deckgauge · Add source · Bitbucket
BBBitbucket

Creating a Bitbucket connection — the workspace is detected from the token.

FieldValue
EmailThe Atlassian account the token belongs to
API tokenCreated with Create API token with scopes, app Bitbucket; sent as HTTP Basic auth and stored encrypted
WorkspaceOptional — detected automatically when the token sees one workspace, chosen from a list when it sees several

How to connect Bitbucket

  1. Open Atlassian API tokens and click Create API token with scopes — not the plain Create API token.
  2. Name it Deckgauge, set an expiry, and choose Bitbucket as the app.
  3. Tick the read scopes: read:user:bitbucket, read:workspace:bitbucket, read:project:bitbucket, read:repository:bitbucket, read:pullrequest:bitbucket, read:pipeline:bitbucket.
  4. Add source → Bitbucket, enter your email, paste the token and click Create & test.
  5. 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

DataWindow on first syncUsed by
Pull requests, with line counts and Jira keys from title, description and branch180 daysPR throughput, cycle time, review metrics, ticket timelines
Approvals and commentswith each PRReview mix, reviewer participation, review quality
Commits on the main branch180 daysCommits per developer, developer heatmap, lead time
Pipelines deployments90 daysDORA 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 a release… branch — is a release, not new work. It is stored but left out of PR throughput and review metrics. A hotfix/… 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

SymptomCauseFix
“This is a plain Atlassian API token”Token created without Bitbucket scopesCreate one with Create API token with scopes → Bitbucket
Repositories missing from the pickerThe account can't read them, or the scope read:repository:bitbucket is missingGrant access in Bitbucket, or recreate the token with every scope above
Deployment frequency is zeroPipelines don't deploy to an environment of type Production, or read:pipeline:bitbucket is missingSet the environment type in Repository settings → Deployments
PRs don't link to Jira ticketsThe board has no Jira project attached and no ticket key prefixesAttach 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

Last updated