Bitbucket

Overview

The Bitbucket integration brings pull request data, push events, and CI build status into Koalr — giving you DORA metrics, PR analytics, cycle time, flow metrics, and deploy risk scoring for teams using Bitbucket Cloud.

Koalr ingests Bitbucket data via a repository or workspace webhook. When a PR is opened, updated, merged, or declined; when commits are pushed; or when a CI build status changes, Bitbucket sends a signed event to Koalr's webhook receiver. Koalr verifies the HMAC-SHA256 signature, resolves the organization, and enqueues the event for processing — typically within seconds.

Only Bitbucket Cloud (bitbucket.org) is supported. Bitbucket Data Center (self-hosted) is on the roadmap.

What Koalr syncs

Data	Sync method	Frequency
Pull requests (open, merged)	Webhook	Real-time
PR reviews and approvals	Webhook	Real-time
Push events (commits)	Webhook	Real-time
CI build status	Webhook	Real-time
Repository metadata	REST backfill	On connect

Backfill on connect: After the webhook is configured, Koalr triggers a one-time REST backfill of the last 90 days of PR history so your dashboards populate immediately.

Connecting Bitbucket

Prerequisites

• A Bitbucket Cloud account with Workspace Admin access (required to manage workspace webhooks).
• A Bitbucket App Password with the following permissions:
  • Repositories: Read
  • Pull requests: Read
  • Webhooks: Read and write (only needed if you want Koalr to auto-register the webhook)

Steps

1. In Koalr, go to Settings → Integrations.
2. Click Connect next to Bitbucket.
3. Enter your workspace slug (the short name in your Bitbucket URL, e.g. my-team), your Bitbucket username, and your App Password.
4. Koalr validates the credentials and saves the integration.
5. Copy the webhook URL and secret shown in the confirmation dialog.
6. In Bitbucket, go to your Workspace Settings → Webhooks (or per-repository under Repository Settings → Webhooks).
7. Click Add webhook.
8. Set the URL to the Koalr webhook URL.
9. Set the Secret to the value from step 5.
10. Enable the following triggers:
    • Pull Request: Created
    • Pull Request: Updated
    • Pull Request: Fulfilled (merged)
    • Pull Request: Rejected (declined)
    • Repository: Push
    • Build: Status created
    • Build: Status updated
11. Click Save and return to Koalr to verify.

Creating a Bitbucket App Password

1. Go to Bitbucket → Personal Settings → App passwords.
2. Click Create app password.
3. Give it a descriptive label (e.g. koalr-integration).
4. Select the required permissions listed above.
5. Copy the generated password — it is shown only once.

Webhook security

Koalr verifies every inbound webhook using the secret you provided. The verification uses HMAC-SHA256 with constant-time comparison against the X-Hub-Signature header — the same scheme used by GitHub. Requests with a missing or invalid signature are rejected and never enqueued.

Keep your webhook secret confidential. If it is ever compromised, disconnect and reconnect the integration from Settings → Integrations → Bitbucket to rotate to a new secret.

Pull request data mapped to Koalr metrics

Bitbucket PR field	Koalr metric
created_on	PR open time (cycle time start)
updated_on (when merged)	Merge time (cycle time end, DORA lead)
state: MERGED	Deployment frequency input
state: DECLINED	PR closed (not counted in throughput)
source.branch.name	Head branch
destination.branch.name	Base branch
participants[].approved	Review approvals
Build state: FAILED	Change failure rate

Feature availability

Feature	Bitbucket	GitHub
PR analytics	Yes	Yes
DORA metrics (all 4)	Yes	Yes
Deploy risk scoring	Yes	Yes
CI build status	Yes	Yes
Review queue	Yes	Yes
Flow metrics	Yes	Yes
Cycle time	Yes	Yes
CODEOWNERS sync	No	Yes
GitHub Copilot analytics	No	Yes
Deploy risk gate (PR block)	No	Yes

Troubleshooting

Events not appearing after webhook setup

In Bitbucket, go to Workspace Settings → Webhooks and check the delivery history for your webhook. Click View on a failed delivery to see the HTTP response. Confirm Koalr returned 200 OK. If not, verify the webhook URL is correct and that the secret matches.

"Signature mismatch" or 200 with no data

The secret entered in Bitbucket must exactly match the secret shown in Koalr's integration dialog. Even a single extra space will cause all deliveries to be rejected. Disconnect and reconnect to generate a fresh secret.

PRs missing after backfill

Backfill covers the last 90 days. Data older than 90 days is not included. If PRs within that window are missing, confirm the App Password has Repositories: Read and Pull requests: Read permissions.

Workspace slug vs. workspace name

The workspace slug is the short identifier in your Bitbucket URL (https://bitbucket.org/<slug>/), not the display name. These may differ — use the slug.