bitbucket-cli

Low-maintenance Bitbucket Cloud tooling built from the live OpenAPI spec: a CLI for software engineers, an MCP server for AI agents, and a Terraform provider for DevSecOps teams.

[!IMPORTANT] https://github.com/FabianSchurig/bitbucket-cli is the canonical repository. If you found this project through the terraform-provider-bitbucket mirror, watch, star, file issues, and contribute in bitbucket-cli.

Start here

Quick links

• Canonical GitHub repository
• Terraform Registry: FabianSchurig/bitbucket
• Mirror repository: terraform-provider-bitbucket
• GitHub Releases
• SonarQube Cloud
• Contributing guide

Install

Homebrew (macOS & Linux)

To install the CLI tool via our custom tap, tap the repository and explicitly trust the formula to reduce supply chain risks:

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-cli
brew install bitbucket-cli

Or to install the MCP server:

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-mcp
brew install bitbucket-mcp

(Note: If you previously tapped the old cask, you can safely untap via brew untap fabianschurig/tap before running the command).

APT (Debian / Ubuntu)

Download the .deb package from the latest release and install it. Supported architectures: amd64, arm64.

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(dpkg --print-architecture)
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.deb"
sudo dpkg -i "bb-cli_${VERSION}_${ARCH}.deb"

Replace bb-cli with bb-mcp to install the MCP server instead.

RPM (Fedora / RHEL / CentOS)

Download the .rpm package from the latest release and install it. Supported architectures: amd64, arm64.

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.rpm"
sudo rpm -i "bb-cli_${VERSION}_${ARCH}.rpm"

Replace bb-cli with bb-mcp to install the MCP server instead.

Scoop (Windows)

scoop bucket add bitbucket https://github.com/FabianSchurig/scoop-bucket
scoop install bb-cli
scoop install bb-mcp

Winget (Windows)

winget install FabianSchurig.bb-cli
winget install FabianSchurig.bb-mcp

Install script

curl -fsSL https://raw.githubusercontent.com/FabianSchurig/bitbucket-cli/main/install.sh | sh

See install.sh options for version selection, binary choice (bb-cli, bb-mcp, or all), and custom install directories.

Other methods

For full installation details see the CLI usage guide and the MCP usage guide.

What this project is

This repository keeps Bitbucket Cloud tooling maintainable by generating most of the surface area from the live Bitbucket OpenAPI spec.

• One API description, three user-facing tools: CLI, MCP, and Terraform all come from the same schema pipeline.
• Thin hand-written runtime: auth, dispatch, output, and Terraform runtime stay generic instead of growing per-endpoint glue.
• Fast spec adoption: new Bitbucket endpoints flow in through generation instead of large manual rewrites.
• Maintenance-first design: the main development effort goes into the shared generators and runtime, not duplicated endpoint code.
• Internal/undocumented endpoints supported the same way: schemas under schema/ can be hand-authored for endpoints that are not in Bitbucket's public OpenAPI spec (for example the project-level branch-restrictions endpoint exposed only via https://bitbucket.org/!api/internal/...). The generators and runtime treat them identically — schema paths may use absolute URLs and the dispatcher passes them through unchanged.

Architecture

flowchart LR
    A[Live Bitbucket OpenAPI spec] --> B[enrich_spec.py]
    B --> C[partition_spec.py]
    C --> D[schema/*-schema.yaml]
    D --> E[oapi-codegen models]
    D --> F[CLI generator]
    D --> G[MCP generator]
    D --> H[Terraform generator]
    E --> I[Shared generated types]
    F --> J[bb-cli]
    G --> K[bb-mcp]
    H --> L[terraform-provider-bitbucket]
    I --> J
    I --> K
    I --> L
    M[Hand-written runtime\nauth, dispatch, output, MCP handler, TF runtime] --> J
    M --> K
    M --> L

In practice:

• CLI exposes Bitbucket operations as terminal commands.
• MCP exposes the same operations as tool calls for AI agents.
• Terraform maps operation groups into generic resources and data sources.
• Hand-written code stays small on purpose; generated code handles endpoint coverage.

CI pipelines

flowchart TD
    A[push / pull_request] --> B[ci.yml]
    A --> C[terraform-tests.yml]
    D[schedule / manual] --> E[schema-sync.yml]
    E --> F[Fetch live spec]
    F --> G[Regenerate code and docs]
    G --> H[Build and test]
    H --> I[Tag new version]
    I --> J[release.yml]
    J --> K[docker.yml]
    I --> L[terraform-release.yml]
    K --> M[Publish to MCP Registry]

• ci.yml: builds, lints, vets, runs Go tests, and sends analysis to SonarQube Cloud.
• terraform-tests.yml: runs mock-based Terraform acceptance and terraform test suites, plus real API tests when credentials exist. See docs/e2e-coverage.md for the current list of endpoints exercised by the real-API tests.
• schema-sync.yml: daily/manual sync that fetches the live Bitbucket spec, regenerates generated artifacts, rebuilds docs, tests everything, and tags a release when the schema changed.
• release.yml: publishes tagged binary releases via GoReleaser.
• docker.yml: builds multi-arch container images for bb-cli and bb-mcp, pushes them to GHCR, publishes their SBOM and CVE reports (see Supply chain: SBOM and CVE reports), and publishes the bb-mcp server to the MCP Registry.
• terraform-release.yml: mirrors the tagged source into terraform-provider-bitbucket and publishes the Terraform provider release.

Schema sync safety

The live OpenAPI document is treated as an input, not as an authority to delete a working API group because of a transient omission. Three mechanisms keep the daily sync from breaking published surface or itself:

• Group preservation: when a group extracts with no paths, partition_spec.py preserves its existing populated schema; a genuinely empty or new group is still written normally.
• Stable operationIds: ids are recorded in the committed lockfile schema/operation-ids.json, keyed by "<method> <path>". An operation keeps its id forever, and ids of removed operations stay reserved — so a sibling endpoint can never inherit an id and silently rename a shipped CLI command, MCP tool, or CRUDConfig reference.
• Operation retention: Atlassian regularly removes deprecated but still functional endpoints from the published spec. Rather than dropping commands in an automatic patch release, partition_spec.py carries such operations forward verbatim from the committed schema, annotated x-bb-cli-retained: true so the schema diff shows exactly what upstream stopped publishing. Retiring one for good is a deliberate act: delete it from schema/*-schema.yaml, and the invariant tests then flag any hand-maintained mapping (for example in CRUDConfig) that still references it.

Acceptance tests in internal/tfprovider/acceptance_test.go are hand-written and are never deleted by schema generation. Generated Terraform fixtures are regenerated from the surviving resource groups, while the schema-sync build and test gate, including the mock Terraform acceptance suites, must pass before any change is committed or released. The generated real-API coverage report makes missing group coverage visible without requiring manual bookkeeping.

Supply chain: SBOM and CVE reports

Every released container image ships with a Software Bill of Materials and a vulnerability report in standard formats. Both are produced from the exact image digest that was pushed to GHCR.

The SBOM is also attached to the image as a signed, digest-bound GitHub attestation, so consumers can verify and fetch it without any access to this repository:

gh attestation verify oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig
gh attestation download oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig

Runtime images are built FROM scratch and contain only the static binary plus CA certificates, so the SBOM is deliberately small and there is no OS package surface to patch.

Vulnerability scan results are additionally uploaded to GitHub code scanning (categories docker-bitbucket-cli and docker-bitbucket-mcp) for maintainers, and the Go module tree is checked by govulncheck in security.yml.

How this differs from DrFaust92/terraform-provider-bitbucket

This project optimizes for breadth, maintenance, and shared infrastructure across interfaces. If you want a heavily hand-modeled Terraform UX, the DrFaust92 provider may feel more familiar. If you want one maintained pipeline that keeps Terraform, CLI, and MCP aligned with Bitbucket Cloud, this repository is designed for that.

Documentation map

Use the short guides on this first page to get started, then switch to the detailed docs for the interface you need.

• CLI: docs/cli.md
• MCP: docs/mcp.md
• Terraform provider docs: docs/index.md and the Terraform Registry docs
• Real-API E2E test coverage: docs/e2e-coverage.md — auto-generated list of which resource groups are exercised by TestAccRealAPI_* tests, and which are still missing coverage.

The Terraform documentation under docs/ is generated. The root README stays focused on orientation, links, architecture, maintenance, and contribution entry points.

Maintenance and contributions

• Read CONTRIBUTING.md before changing generators or runtime code.
• Do not hand-edit generated files; fix the generator or schema source instead.
• Prefer changes that improve the shared pipeline or hand-written runtime across all endpoints.
• Open issues and pull requests in the canonical bitbucket-cli repository.