Bitbucket

The mechanics that Bitbucket shares with GitHub and GitLab (auto-linking by identifier, the linked-request panel, manual linking by URL, status automation, the branch-name helper, and the outbound completion comment) are documented once in Git linking, status sync, and branch names. This page covers what is specific to Bitbucket: the OAuth consumer, connecting a workspace, and linking a repository to a project.

What it does

• Pull request linking: name a branch or a pull request title with an Ithura issue key (a project identifier plus a number, like PAR-123) and Ithura records a link between that pull request and the issue.
• Status sync: as the linked pull request changes state, Ithura moves the issue. Opened maps the issue to a Started-group state, merged maps it to a Completed-group state (and stamps the completion date), and declined or superseded maps it to a Cancelled-group state. Converting a pull request to a draft is a no-op: the link records the draft state but the issue does not move.
• Manual linking: link a pull request to an issue by pasting its URL (https://bitbucket.org/{workspace}/{repo}/pull-requests/{id}), and unlink with one click. An issue can carry several linked pull requests at once.

Connect (workspace admin)

The Bitbucket connect flow is driven by the OAuth endpoints under .../integrations/bitbucket/install/ and /integrations/bitbucket/callback/. A workspace admin clicks Connect Bitbucket in the workspace Integrations settings and approves the OAuth consent. Starting the flow requires the Admin role. On return, Ithura stores the encrypted access and refresh tokens for the workspace and sends the admin back to the workspace Integrations screen. The connection, once made, is what powers repository linking and the pull request status sync.

Link a Bitbucket repository (project admin)

A project admin links one Bitbucket repository to one Ithura project. Linking:

1. Records the Bitbucket repository against the Ithura project.
2. Mints a per-link webhook token.
3. Tries to auto-create the repository webhook via the Bitbucket API, subscribed to pull request events (created, updated, fulfilled, rejected) and signed with the per-repo secret.

Because Bitbucket retired its account-wide repository listing endpoints, the repo picker is scoped to a single Bitbucket workspace: you provide the Bitbucket workspace slug and Ithura lists the repositories in it.

If the connected token does not carry the Webhooks scope, the auto-create step is skipped, the link is still saved, and Ithura returns the manual webhook URL so an admin can add it by hand. In that case add a webhook in the Bitbucket repository settings:

Bitbucket webhook field	Value
URL	https://<api-host>/webhooks/bitbucket/<token>/
Triggers	Pull request: Created, Updated, Merged, Declined

Ithura matches the token in the URL against the linked repository, so the URL must carry the exact value Ithura returned when you linked the repo.

Using it

• Put an issue key such as PAR-123 in a branch name or a pull request title (for example PAR-123-fix-login), or copy a ready-made branch name from the issue, and Ithura links the pull request automatically the moment its webhook arrives.
• To link a pull request that already exists, paste its URL of the form https://bitbucket.org/{workspace}/{repo}/pull-requests/{id} into the issue's Linked pull requests panel.
• As the pull request opens, merges, or is declined, the linked issue moves to the matching state.

Status mapping is shared across all git providers and is configurable per project in the workspace Git status mapping settings. For the full behavior of linking, status sync, branch names, and the completion comment, see Git linking, status sync, and branch names.

Troubleshooting

• Nothing links after wiring the repo: confirm the webhook is enabled in Bitbucket and subscribed to pull request events, and that Bitbucket shows successful deliveries.
• The webhook was not created automatically: the connected token is missing the Webhooks scope. Reconnect the workspace after granting Webhooks read and write on the consumer, or add the webhook by hand using the returned URL.
• 401 or signature mismatch: re-link the repository to mint a fresh webhook token and update the Bitbucket webhook URL.
• The OAuth return fails or you see "Bitbucket is not configured on this instance": the integration has not been enabled for your instance yet.
• The repo picker returns nothing: repository listing is scoped to a Bitbucket workspace slug, so make sure you entered the workspace whose repositories you want.