README.md

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

Audience	Best fit	Start here
DevSecOps engineers	Terraform provider	Terraform Registry, generated provider docs, example: bitbucket_tags
Software engineers / computer scientists	bb-cli	CLI usage guide
AI agents / agent platform users	bb-mcp	MCP usage guide

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

Method	Command
Go install	go install github.com/FabianSchurig/bitbucket-cli/cmd/bb-cli@latest
Docker	docker pull ghcr.io/fabianschurig/bitbucket-cli:latest
Download binaries	GitHub Releases

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

Loading

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]

Loading

• 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. 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. If Bitbucket removes only some endpoints, that is treated as an intentional change: generated code and CRUDConfig are rebuilt, and the invariant tests fail if any hand-maintained mapping still references a removed operation.

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.

Artifact	Format	Where to get it
Image SBOM	SPDX 2.3 JSON	sbom-bitbucket-cli.spdx.json / sbom-bitbucket-mcp.spdx.json on the matching GitHub Release, or as a signed attestation on the image itself
Image CVE report	Grype JSON + plain-text table	cves-bitbucket-cli.{json,txt} / cves-bitbucket-mcp.{json,txt} on the matching GitHub Release
Source SBOM	SPDX JSON	Attached to the GitHub Release by release.yml (covers the git tag, not the image)

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

Aspect	DrFaust92/terraform-provider-bitbucket	FabianSchurig/bitbucket
Maintenance model	Hand-written provider resources	Mostly generated from the live Bitbucket OpenAPI spec
Scope	Terraform provider only	Terraform provider + CLI + MCP server in one canonical repo
API coverage model	Curated, typed resources	Broad endpoint coverage through grouped generic resources/data sources
Update flow	Manual feature work per resource	Schema sync pipeline regenerates code and docs
Resource shape	Resource-specific typed fields	Generic params, response fields, and raw API response
Best fit	Opinionated Terraform workflows	Teams that want fast Bitbucket API coverage and shared tooling across Terraform, shells, and AI agents

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.