Skip to main content
Version: 15.2.1

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​

VariableRequiredDefaultDescription
BITBUCKET_ACCESS_TOKENOne auth mode—Bitbucket access token for Bearer auth (workspace, project, or repository scope).
BITBUCKET_API_USERNAMEOne auth mode—Username for HTTP Basic Authentication.
BITBUCKET_API_TOKENOne auth mode—App password / access token for Basic Auth.
BITBUCKET_URLNohttps://api.bitbucket.orgBase URL of the Bitbucket API.
BITBUCKET_HTTP_TIMEOUTNo30sTimeout for HTTP requests (Go duration).
BITBUCKET_WORKSPACENo(empty)Restrict sync to a single workspace slug. When empty, ibdm enumerates all accessible workspaces.
BITBUCKET_WEBHOOK_SECRETRun(empty)HMAC secret for webhook signature validation.
BITBUCKET_WEBHOOK_PATHNo/bitbucket/webhookHTTP 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 as Authorization: Bearer <token>.
  • Basic Auth — set both BITBUCKET_API_USERNAME and BITBUCKET_API_TOKEN. Sent as HTTP Basic Authentication.

Supported data types​

TypeSyncWebhook
repository✅✅
pipeline✅—

Subscribed webhook events:

Event keyProduces
repo:pushrepository upsert
repo:updatedrepository upsert
pullrequest:fulfilledrepository 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 mappingSyncWebhookIts 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​

  1. In the Bitbucket repository or workspace, go to Repository settings → Webhooks → Add webhook.
  2. Set URL to your public ibdm URL followed by BITBUCKET_WEBHOOK_PATH (default /bitbucket/webhook).
  3. Set Secret to the value of BITBUCKET_WEBHOOK_SECRET. Bitbucket signs the payload as X-Hub-Signature: sha256=<hex-hmac>; ibdm rejects requests with a missing or invalid signature.
  4. 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, and pullrequest:fulfilled event keys respectively).

See also​