bb - SKILL.md Agent Skill

name: bb description: Interact with Bitbucket Data Center from an AI agent. Covers pull requests, build status, branches, tags, commits, repository search, and code insights. Use bb --help to discover all available commands.

bb — Bitbucket Data Center CLI

bb is a CLI for recent versions of Bitbucket for Data Center with a live-behavior-first design. Use it to query and mutate Bitbucket resources during autonomous coding workflows.

Version note. This skill was generated by bb {{BB_VERSION}}. Run bb ai skill show to print a version-specific skill that reflects the exact capabilities of your installed binary.

Installation

# Via npx skills (matches the bb release at the time of install):
npx skills add vriesdemichael/bitbucket-data-center-cli

# Version-accurate skill (always matches your installed bb binary):
bb ai skill show > .agents/skills/bb/SKILL.md

# Or let bb write it for you:
bb ai skill install          # project scope: .agents/skills/bb/SKILL.md
bb ai skill install --global # user scope:    ~/.agents/skills/bb/SKILL.md

Authentication

Before using bb, authenticate against your Bitbucket instance:

bb auth login https://bitbucket.example.com --token <your-pat>
bb auth status

Agents cannot complete OAuth flows. Always use a Personal Access Token (PAT). Create one at: bb auth token-url

Discovering Commands

Every command has built-in help. Prefer --help over guessing:

bb --help
bb pr --help
bb pr get --help

Common Workflows

1. Start a feature

# Find the right repository
bb search repos "payment"

# Check the default branch exists
bb ref resolve --repo MYPROJ/payments main

# Clone (get the URL, then run git clone)
bb ai mcp tools          # or just use git directly with the URL from:
bb repo browse content --repo MYPROJ/payments

# Check for an existing branch
bb branch list --repo MYPROJ/payments --filter feature/my-work

2. Open a pull request (optionally as a draft)

# Open a normal PR
bb pr create --repo MYPROJ/payments --from-ref feature/my-work --to-ref main --title "Add payment retries"

# Open a draft PR (Bitbucket DC 8.0+) — signals work-in-progress, not ready for review
bb pr create --repo MYPROJ/payments --from-ref feature/my-work --to-ref main --title "Add payment retries" --draft

# Assign reviewers at creation (repeatable or comma-separated)
bb pr create --repo MYPROJ/payments --from-ref feature/my-work --to-ref main --title "Add payment retries" --reviewers alice,bob

When a draft PR is ready for review, flip the draft flag (the --version is the current PR version for optimistic locking, from bb pr get):

# Mark a draft PR as ready for review
bb pr update 42 --repo MYPROJ/payments --version 3 --draft=false

# Convert an open PR back to draft
bb pr update 42 --repo MYPROJ/payments --version 3 --draft

3. Check whether a PR is ready to merge

# Get approval status and merge state
bb pr get --repo MYPROJ/payments 42

# Check open reviewer tasks
bb pr task list --repo MYPROJ/payments --pr 42

# Check CI status on HEAD commit
bb build status get <commit-sha>

# Know what CI must pass before merging
bb build required list --repo MYPROJ/payments

4. Merge automatically once checks pass

Auto-merge lets Bitbucket complete the merge as soon as required builds pass and all approvals are in, instead of polling and merging manually (Bitbucket DC 8.0+). Only enable it after review feedback is addressed and required checks are green.

# Inspect current auto-merge configuration
bb pr auto-merge get --repo MYPROJ/payments 42

# Enable auto-merge (default strategy: no-ff). Prefer a rebase strategy for linear history.
bb pr auto-merge enable --repo MYPROJ/payments 42 --strategy rebase-ff-only

# Cancel auto-merge
bb pr auto-merge disable --repo MYPROJ/payments 42

Valid --strategy values: no-ff, ff-only, rebase-no-ff, rebase-ff-only, squash, squash-ff-only.

5. Address review feedback

# Read inline review comments
bb pr comment list --repo MYPROJ/payments 42 --path src/main/java/com/example/PaymentService.java

# Post a progress note after fixing
bb repo comment create --repo MYPROJ/payments --pr 42 "Fixed in <commit>. Please re-review."

6. Diagnose a CI failure

# Get build statuses for a specific commit
bb build status get <commit-sha>

# Get commit details for context
bb commit get --repo MYPROJ/payments <commit-sha>

# Compare against the previous green commit
bb commit compare --repo MYPROJ/payments --from <green-sha> --to <failing-sha>

7. Release tagging

# Find the current latest tag
bb tag list --repo MYPROJ/payments

# Create a new release tag
bb tag create --repo MYPROJ/payments v1.2.3 main

8. File browse/edit, comparison and archives

Read or edit repository files over REST without cloning, compare refs/branches, or download repository archives:

# Print raw file contents to stdout
bb repo cat README.md --repo MYPROJ/payments --at main

# Edit/create a file directly via REST
bb repo edit README.md --repo MYPROJ/payments --branch main --message "Update README" --content "New content..."

# Compare commits or branches to list changed files
bb repo compare main feature/my-work --repo MYPROJ/payments

# Show a unified diff of changes between two refs
bb repo compare main feature/my-work --repo MYPROJ/payments --diff

# Download a repository archive (defaults to zip format)
bb repo archive --repo MYPROJ/payments --at main --output payments-main.zip

# Stream repository archive to stdout
bb repo archive --repo MYPROJ/payments --format tar.gz -o - > archive.tar.gz

9. Hook scripts management

View and configure repository hook scripts and trigger configurations (Bitbucket DC 7.14+):

# List all configured hook scripts and their triggers on a repo
bb repo hook-script list --repo MYPROJ/payments

# Enable or update triggers for a hook script
bb repo hook-script set 42 --repo MYPROJ/payments --trigger pr:opened,pr:from_ref_updated

# Remove a hook script configuration
bb repo hook-script remove 42 --repo MYPROJ/payments

10. SSH keys and HTTP Access Tokens

Manage personal SSH keys or repository/project-level SSH access keys, and create/manage HTTP access tokens:

# --- SSH Keys ---
# List your personal SSH keys
bb ssh-key list

# Add a personal SSH key
bb ssh-key add ~/.ssh/id_ed25519.pub --label "My Laptop"

# List repository-level SSH access keys (use --project for project-level)
bb repo ssh-key list --repo MYPROJ/payments

# Add repository-level SSH access key with read-write permission
bb repo ssh-key add ~/.ssh/deploy_key.pub --repo MYPROJ/payments --label "CI Deploy" --read-write

# --- HTTP Access Tokens ---
# List your HTTP access tokens (defaults to user scope)
bb auth token list

# Create a project access token (Bitbucket DC 8.2+)
bb auth token create "CI Token" --project MYPROJ --permission PROJECT_READ --expiry-days 90

# Revoke an access token by ID
bb auth token revoke token-id-123

11. Scoped builds and deployments

Associate builds and deployments with specific commits, or view statistics across multiple commits (Bitbucket DC 7.4+):

# --- Repository-scoped Builds ---
# Set a build status for a commit in a specific repository
bb build set <commit-sha> --repo MYPROJ/payments --key "ci/test" --state SUCCESSFUL --url "https://ci.example.com" --name "Unit Tests"

# Get a build status by key
bb build get <commit-sha> --repo MYPROJ/payments --key "ci/test"

# Delete a repository-scoped build status
bb build delete <commit-sha> --repo MYPROJ/payments --key "ci/test"

# View build statistics summary for multiple commits
bb build status stats <commit-sha-1> <commit-sha-2> <commit-sha-3>

# --- Deployments ---
# Create or update a deployment status for a commit
bb deployment create <commit-sha> --repo MYPROJ/payments --key "prod-deploy" --display-name "Production Deploy" --state SUCCESSFUL --url "https://deploy.example.com" --env-key "prod" --env-name "Production" --deployment-sequence-number 1

# Get deployment status details
bb deployment get <commit-sha> --repo MYPROJ/payments --key "prod-deploy"

# Delete a deployment status
bb deployment delete <commit-sha> --repo MYPROJ/payments --key "prod-deploy"

# --- Code Insights Annotations ---
# Set a code insight annotation on a commit report
bb insights annotation set <commit-sha> lint a1 --repo MYPROJ/payments --message "Style violation" --severity LOW

# List annotations on a commit
bb insights annotation list <commit-sha> --repo MYPROJ/payments

MCP Server

bb ships a built-in MCP server for IDE integration. It exposes Bitbucket operations as MCP tools that AI agents can call directly without constructing CLI arguments.

# List all available MCP tools
bb ai mcp tools

# Start the server (used by IDE MCP clients, not invoked manually)
bb ai mcp serve

# Restrict to a read-only PAT
bb ai mcp serve --token <read-only-pat>

# Expose only specific tools
bb ai mcp serve --tools get_pull_request,list_pr_comments,get_build_status

VS Code MCP configuration (`settings.json`)

{
  "mcp": {
    "servers": {
      "bb": {
        "type": "stdio",
        "command": "bb",
        "args": ["ai", "mcp", "serve"]
      }
    }
  }
}

Key MCP tools

Tool	Purpose
`get_pull_request`	PR details, approvals, merge state
`list_pr_comments`	Review thread contents
`list_pr_tasks`	Open tasks blocking merge
`get_build_status`	CI status on a commit
`list_required_builds`	What CI must pass before merging
`get_repository_clone_info`	HTTPS and SSH clone URLs
`resolve_ref`	Check branch/tag exists, get tip SHA
`list_pull_requests`	Open PRs on a repo
`create_pull_request`	Open a PR (supports `draft`)
`enable_auto_merge`	Auto-merge a PR once checks pass
`disable_auto_merge`	Cancel auto-merge on a PR
`add_pr_comment`	Post a review comment
`list_branches`	All branches, with optional filter
`list_tags`	All tags
`compare_refs`	Commits between two refs
`list_commits`	Walk commit history
`get_commit`	Single commit details
`submit_pr_review`	Approve or unapprove a PR
`merge_pull_request`	Merge when ready
`create_tag`	Tag a commit for release
`set_build_status`	Report CI results back to Bitbucket
`search_repositories`	Find repositories by name/project

Output Modes

All commands support --json for machine-readable output:

bb pr get --repo MYPROJ/payments 42 --json
bb tag list --repo MYPROJ/payments --json

Error Reporting

If bb behaves unexpectedly, create an issue:

https://github.com/vriesdemichael/bitbucket-data-center-cli/issues/new

If you cannot open the URL directly, ask the user to file the issue on your behalf.

bb