feat(tools/bitbucket): Bitbucket forge + tracker bridge (Atlassian)

[potiuk]

Add tools/bitbucket/ as a forge + tracker bridge for Bitbucket (Atlassian Cloud and self-hosted Data Center), analogous to tools/github/ and the tools/gitlab/ bridge (#305). Bitbucket is a major Git forge with no coverage today, and it has deep Jira integration — pairing naturally with the existing tools/jira/ tracker bridge.

Capabilities to provide (mirror the GitHub bridge):

• Issue read/write (Bitbucket issues and linked Jira, via tools/jira/)
• Pull-request read/write: view/list, create/edit/merge, comment, review/approve
• Repo metadata, branch permissions
• Pipelines read for CI status checks
• Bitbucket Cloud REST API + Data Center REST API (note: the two API flavours differ — abstract behind one bridge)

Why: Bitbucket is the default forge across the Atlassian enterprise ecosystem and a large share of corporate OSS. It historically hosted Mercurial too (dropped in 2020), which is part of why Hg projects scattered — so a Bitbucket bridge plus the Mercurial bridge together recover that displaced population. With Jira already bridged, Bitbucket closes the loop on the full Atlassian adopter stack.

Reference:

• Bitbucket Cloud REST API: https://developer.atlassian.com/cloud/bitbucket/rest/
• Bitbucket Data Center REST API: https://developer.atlassian.com/server/bitbucket/rest/
• Existing forge bridges to mirror: tools/github/, tools/gitlab/ (feat(tools/gitlab): add tracker + forge bridge for GitLab-hosted projects #305); pairs with tools/jira/

[KatalKavya96]

@potiuk Hi I would like to work on this issue. I will start by mirroring the existing tools/github/ and tools/gitlab/ bridge structure and add the initial tools/bitbucket/ setup with docs, auth/config, and basic read support. Can you please assign it to me if possible? Thanks!

[potiuk]

Feel free. We have not yet agreed if we should assign issues to people when tjey ask - it's something that for example might block others and 'stall' implementation. But feel free to start implementing on it anyway.

[KatalKavya96]

@potiuk I have started studying the existing tool patterns for this issue.

From the current main, I noticed that tools/github/ provides the main forge/tracker capability reference, tools/jira/ gives the closest Atlassian REST bridge implementation pattern, and tools/gitlab/ is still not present yet since #305 is open.

Would it make sense to approach tools/bitbucket/ in phased PRs?

My proposed split is:

1. PR 1 — Initial Bitbucket bridge skeleton + read-only foundation

   • Add tools/bitbucket/
   • Document capability, config, Cloud vs Data Center model, output contract, and write-path discipline
   • Add initial read-only commands such as auth/preflight, repo metadata, and open PR listing/fetching
   • Add mocked tests for Cloud/Data Center response normalisation

2. PR 2 — Change-request / PR operations

   • Map Bitbucket pull requests to the contract:change-request verbs: list/get/discussion/status
   • Add review/comment/approve/decline/merge paths after the read-only base is stable

3. PR 3 — Tracker support

   • Add Bitbucket Issues support where available
   • Clarify Jira handoff for adopters using Jira as the tracker and Bitbucket as the forge

4. PR 4 — Branch permissions + Pipelines

   • Add branch restriction/permission reads
   • Add Bitbucket Pipelines status reads for PR/status checks

I am planning to keep the first PR small and reviewable, likely focused on the bridge contract plus read-only operations, before adding write operations. Please let me know if you prefer a different first slice. Thanks!

[potiuk]

Sure. Looks good !