Bitbucket Connector
The Bitbucket connector ingests data from Bitbucket Cloud into the Catalog. It runs through the ibdm binary in one of two modes:
- Sync — pull-based: queries the Bitbucket REST API and exits.
- Run — push-based: exposes a webhook endpoint that receives Bitbucket events.
Commands
ibdm sync bitbucket --include-internal-mappings=all
ibdm run bitbucket --include-internal-mappings=all
The commands use every internal mapping of the source. To select only some of them, or to add mappings of your own, see Mappings.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
BITBUCKET_ACCESS_TOKEN | One auth mode | — | Bitbucket access token for Bearer auth (workspace, project, or repository scope). |
BITBUCKET_API_USERNAME | One auth mode | — | Username for HTTP Basic Authentication. |
BITBUCKET_API_TOKEN | One auth mode | — | App password / access token for Basic Auth. |
BITBUCKET_URL | No | https://api.bitbucket.org | Base URL of the Bitbucket API. |
BITBUCKET_HTTP_TIMEOUT | No | 30s | Timeout for HTTP requests (Go duration). |
BITBUCKET_WORKSPACE | No | (empty) | Restrict sync to a single workspace slug. When empty, ibdm enumerates all accessible workspaces. |
BITBUCKET_WEBHOOK_SECRET | Run | (empty) | HMAC secret for webhook signature validation. |
BITBUCKET_WEBHOOK_PATH | No | /bitbucket/webhook | HTTP path for inbound webhook events. |
Authentication
Bitbucket supports two mutually exclusive authentication modes. Setting both is a configuration error.
- Bearer Token — set
BITBUCKET_ACCESS_TOKEN. Sent asAuthorization: Bearer <token>. - Basic Auth — set both
BITBUCKET_API_USERNAMEandBITBUCKET_API_TOKEN. Sent as HTTP Basic Authentication.
Supported data types
| Type | Sync | Webhook |
|---|---|---|
repository | ✅ | ✅ |
pipeline | ✅ | — |
Subscribed webhook events:
| Event key | Produces |
|---|---|
repo:push | repository upsert |
repo:updated | repository upsert |
pullrequest:fulfilled | repository upsert |
Internal mappings
ibdm mappings list bitbucket prints the internal mappings of this source, and the Internal Mappings reference lists the Item Type each one writes.
| Internal mapping | Sync | Webhook | Its relationships point at |
|---|---|---|---|
repositories | ✅ | ✅ | — |
pipelines | ✅ for every repository | — | repositories |
The sync walks the repositories of the workspaces as soon as either mapping is selected, and fetches the pipelines of each repository while walking them. Selecting pipelines alone works, but its items then relate to repository items that nothing creates: select repositories too.
Setting up a Bitbucket webhook
- In the Bitbucket repository or workspace, go to Repository settings → Webhooks → Add webhook.
- Set URL to your public
ibdmURL followed byBITBUCKET_WEBHOOK_PATH(default/bitbucket/webhook). - Set Secret to the value of
BITBUCKET_WEBHOOK_SECRET. Bitbucket signs the payload asX-Hub-Signature: sha256=<hex-hmac>;ibdmrejects requests with a missing or invalid signature. - Under Triggers, select the events that match the data you want: Repository → Push, Repository → Updated, and Pull request → Merged (these deliver the
repo:push,repo:updated, andpullrequest:fulfilledevent keys respectively).