Skip to main content
Version: v2 (current)

Bitbucket Integration with PanDev Metrics

import IdealImage from "@theme/IdealImage"; import Head from "@docusaurus/Head";

TL;DR. This guide connects Bitbucket to PanDev Metrics in about 10 minutes. For Bitbucket Cloud you create an app password; for Bitbucket Server or Data Center you create a personal access token. Both flows end the same way: paste the credentials into PanDev Metrics, pick repositories, and verify that pull-request webhooks arrive. Audience: admin.

Before you begin​

  • PanDev Metrics version ≥ 1.0.250 (Cloud users always meet this)
  • Admin access to your PanDev Metrics tenant
  • A Bitbucket user with Admin access on the workspaces / projects to analyse (use a service account)
  • For on-prem PanDev Metrics: outbound 443 to bitbucket.org or to your Bitbucket Server / Data Center host
  • For Bitbucket to reach an on-prem PanDev Metrics deployment: the PanDev Metrics host must be reachable from Bitbucket at the public webhook URL

:::tip Use a service account Create a Bitbucket user dedicated to PanDev Metrics (for example pandev-metrics-bot). Add it to the relevant workspaces with Admin access. This keeps automated PR comments distinct from human reviewers. :::

Step 1 — Create credentials in Bitbucket​

The credential type depends on which Bitbucket edition you run.

Bitbucket Cloud — create an app password​

  1. Sign in to Bitbucket Cloud as the service account.
  2. Open Personal Settings → App passwords.
  3. Select Create app password.
  4. Configure permissions:
PermissionAccess
RepositoriesRead, Write
Pull requestsRead, Write
WebhooksRead and write
  1. Select Create and copy the app password — Bitbucket Cloud shows it only once.

You'll also need your Bitbucket username (visible at the top-right of any Bitbucket page).

Bitbucket Server / Data Center — create a personal access token​

  1. Sign in to Bitbucket Server / Data Center as the service account.
  2. Open Manage Account → Personal access tokens.
  3. Select Create a token.
  4. Configure permissions:
PermissionAccess
RepositoryRead, Write
Pull RequestRead, Write
  1. Select Create and copy the token — it won't be shown again.

Step 2 — Open the Bitbucket integration screen in PanDev Metrics​

Sign in to PanDev Metrics as a workspace admin and open Settings → Integrations → Bitbucket.

Pick the edition you set up: Bitbucket Cloud or Bitbucket Server / Data Center.

Step 3 — Enter credentials and host​

The fields depend on the edition.

For Bitbucket Cloud:

FieldValue
UsernameYour Bitbucket Cloud username
App passwordValue from Step 1

For Bitbucket Server / Data Center:

FieldValue
Server URLhttps://bitbucket.acme.example
Personal access tokenValue from Step 1

Select Check connection. PanDev Metrics calls the Bitbucket API and reports the authenticated user plus the count of accessible repositories.

When the check passes, select Activate.

Step 4 — Pick the repositories to monitor​

PanDev Metrics shows the list of workspaces (Cloud) or projects (Server / Data Center) visible to the credentials. Select the repositories you want to analyse and save.

PanDev Metrics starts a one-time backfill of the last 30 days of commits and pull requests.

Step 5 — Verify webhook registration​

PanDev Metrics registers webhooks per repository automatically. On Bitbucket, open any selected repository and go to:

  • Repository settings → Webhooks (Cloud)
  • Repository settings → Webhooks (Server / Data Center)

You should see a hook pointing at the PanDev Metrics ingest URL. For reference, PanDev Metrics handles these endpoints (URLs are filled in automatically during activation):

EventPanDev Metrics endpoint (informational)
Repository lifecycle/v1/bitbucket/webhook/repository
Pull-request events/v1/bitbucket/webhook/merge-request

Recent deliveries should return HTTP 200 within seconds.

Verify​

Open Settings → Integrations → Bitbucket in PanDev Metrics. You should see:

  • A green Connected badge
  • The count of selected repositories
  • The timestamp of the Last sync (no older than 30 minutes once backfill completes)

Then open a dashboard with DORA metrics — within ~15 minutes after activation, lead-time and PR-cycle-time tiles should reflect Bitbucket data.

Troubleshooting​

Check connection returns "401 Unauthorized"

For Cloud — the app password is wrong, or the username is misspelled (use your account username, not your display name or email). For Server / Data Center — the personal access token is expired or revoked. Re-create the credential in Step 1.

Check connection returns "404 Not Found" on Server / Data Center

The Server URL has an extra path or trailing slash. Use the bare host, for example https://bitbucket.acme.example, not https://bitbucket.acme.example/bitbucket/. If you run Bitbucket behind a reverse proxy with a context path, contact your administrator.

Webhooks register but deliveries fail with timeout

The Bitbucket instance can't reach the PanDev Metrics webhook URL. For on-prem PanDev Metrics, confirm the host is reachable from Bitbucket on its public URL. From the Bitbucket server, try curl -I <pandev-public-url>/v1/bitbucket/webhook/merge-request.

PR comments don't appear

The app password / token lacks Pull requests: Write, or Post PR comments is disabled in PanDev Metrics. Open Settings → Integrations → Bitbucket → Advanced to confirm. The setting honours per-repository overrides — confirm the target repo isn't excluded.

Only some repositories sync

The service account doesn't have access to the missing repositories. Add the user to the relevant workspaces (Cloud) or grant project-level permissions (Server / Data Center), then re-run Check connection.

What gets collected​

PanDev Metrics ingests, per selected repository:

  • Commits (SHA, author, timestamp, message, file stats)
  • Branches and tags
  • Pull requests (open / merged / declined) and their reviews, comments, and approvals
  • Pipeline / CI status attached to PRs (when present)

Source code itself is not stored. For details, see How the plugin works.

FAQ​

Which Bitbucket editions are supported?​

Bitbucket Cloud, Bitbucket Server, and Bitbucket Data Center are all supported. The setup flow is the same except for the credential type — app password on Cloud, personal access token on Server / Data Center.

What's the minimum permission set?​

For Cloud: Repositories: Read+Write and Pull requests: Read+Write on the app password. For Server / Data Center: Repository: Read+Write and Pull Request: Read+Write on the PAT. The write scopes are used for posting DORA-metric comments — disable commenting in PanDev Metrics if you prefer read-only.

Can I use Bitbucket OAuth instead of an app password?​

Not currently. Bitbucket Cloud OAuth-app flow is not implemented. PanDev Metrics relies on app passwords for Cloud and personal access tokens for Server / Data Center.

How often is data refreshed?​

Webhooks deliver pull-request and commit events in real time — usually within seconds. PanDev Metrics also runs a reconciliation poll every 15 minutes to catch any missed deliveries.

How long does the initial backfill take?​

PanDev Metrics backfills the last 30 days when you activate the integration. For 50 repositories this typically takes 5-15 minutes. Larger workspaces can take an hour. Sync after backfill is real-time via webhooks.

Can I limit the integration to specific repositories?​

Yes. After activation, deselect repositories on the integration screen at any time. PanDev Metrics removes webhook registrations on the deselected repos within minutes.

What's the difference between Bitbucket Server and Data Center?​

Server is the single-node self-hosted edition (deprecated by Atlassian for new installs). Data Center is the clustered self-hosted edition. From PanDev Metrics' perspective the API is identical — point at the host URL and provide a PAT.

Next steps​