mcpField
B
bitbucket

bitbucket

github.com/jorgemuza开发069 次安装今天更新
代码仓库

关于 bitbucket

通过 `orbit` 命令行管理 Bitbucket 的技能，适用于 Server/Data Center 和 Cloud。它涵盖仓库、拉取请求、分支、提交、项目和用户操作，并支持配置档案及 JSON 输出以便脚本处理。

主要功能

  1. 01管理项目与仓库
  2. 02审查和更新拉取请求
  3. 03列出分支、标签和提交
  4. 04搜索项目与仓库
  5. 05使用配置档案和 JSON 输出

适用场景

  1. 01查看各项目中的仓库
  2. 02审查拉取请求并作出处理
  3. 03用 JSON 自动化 Bitbucket 查询
  4. 04管理默认审阅者条件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jorgemuza/orbit --skill bitbucket

安装后在 Claude Code 中输入/bitbucket确认已加载。

附带文件references/commands.md

详细介绍

使用 orbit CLI 操作 Bitbucket

通过 orbit CLI 管理 Bitbucket 仓库、拉取请求、分支、标签、提交、项目和用户。支持 Bitbucket Server/Data Center 和 Cloud，并支持多配置文件以及 1Password 密钥解析。

前提条件

  1. 已安装 orbit CLI — 如果 which orbit 执行失败，请通过以下方式安装：
    • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
    • macOS/Linux（脚本）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
    • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
  2. ~/.config/orbit/config.yaml 中已配置 bitbucket 服务的配置文件
  3. 有效的凭据（Server 使用 Personal Access Token 或 Bearer token；Cloud 使用 app password）——可存储为 1Password（op://）或 Infisical（infisical://）引用

快速参考

所有命令遵循以下格式：orbit -p <profile> bitbucket <command> [flags]

别名：orbit -p <profile> bb <command> [flags]

所有命令均支持通过 -o json 输出 JSON。完整命令详情和所有标志请参阅 references/commands.md。

对于使用自签名证书的自托管实例，请在服务配置中添加 tls_skip_verify: true。如需通过代理访问，请添加 proxy: socks5://host:port。

寻址约定

Bitbucket Server/Data Center 使用项目键 + 仓库 slug来标识仓库。这是大多数命令要求提供的两个位置参数：

  • 项目键：大写的短代码（例如，L3SUP、MYPROJ）
  • 仓库 slug：小写的连字符名称（例如，agents-sre、my-service）

你可以从 Bitbucket Server URL 中提取这些信息：

https://git.example.com/projects/L3SUP/repos/agents-sre/
                                  ^^^^^       ^^^^^^^^^^
                              project-key     repo-slug

核心工作流

浏览项目和仓库
# List all projects
orbit -p myprofile bb project list

# View project details
orbit -p myprofile bb project view L3SUP

# List repositories in a project
orbit -p myprofile bb repo list L3SUP

# View repo details (includes clone URLs)
orbit -p myprofile bb repo view L3SUP agents-sre
管理仓库
# Create a repo
orbit -p myprofile bb repo create L3SUP --name my-service --description "Payment API"

# Update a repo
orbit -p myprofile bb repo edit L3SUP my-service --description "New description"

# Delete a repo (irreversible)
orbit -p myprofile bb repo delete L3SUP my-service

# Fork a repo into another project
orbit -p myprofile bb repo fork L3SUP agents-sre --target-project MYPROJ

# List forks
orbit -p myprofile bb repo forks L3SUP agents-sre

# Manage user permissions (REPO_READ, REPO_WRITE, REPO_ADMIN)
orbit -p myprofile bb repo permissions L3SUP agents-sre
orbit -p myprofile bb repo grant L3SUP agents-sre john.doe --permission REPO_WRITE
orbit -p myprofile bb repo revoke L3SUP agents-sre john.doe
处理拉取请求

Bitbucket 使用“拉取请求”（PR），与 GitHub 相同。

# List open PRs (default)
orbit -p myprofile bb pr list L3SUP agents-sre

# List merged PRs
orbit -p myprofile bb pr list L3SUP agents-sre --state merged

# List all PRs
orbit -p myprofile bb pr list L3SUP agents-sre --state all

# View PR details (shows from/to branches, reviewers, approval status)
orbit -p myprofile bb pr view L3SUP agents-sre 42

# Create a PR
orbit -p myprofile bb pr create L3SUP agents-sre \
  --from feature/new --to main --title "Add new feature"

# Create a PR with reviewers
orbit -p myprofile bb pr create L3SUP agents-sre \
  --from feature/new --to main --title "Add feature" \
  --reviewers john.doe,jane.smith

# View PR diff (for code review)
orbit -p myprofile bb pr diff L3SUP agents-sre 42

# View PR diff with more context lines
orbit -p myprofile bb pr diff L3SUP agents-sre 42 --context 10

# Merge a PR
orbit -p myprofile bb pr merge L3SUP agents-sre 42

# Merge a PR bypassing review checks (requires repo admin)
orbit -p myprofile bb pr merge L3SUP agents-sre 42 --bypass-review

# Approve a PR
orbit -p myprofile bb pr approve L3SUP agents-sre 42

# Remove approval from a PR
orbit -p myprofile bb pr unapprove L3SUP agents-sre 42

# Can it merge, and if not why not
orbit -p myprofile bb pr merge-status L3SUP agents-sre 42

# Edit the title or description (reviewers and their approvals are preserved)
orbit -p myprofile bb pr edit L3SUP agents-sre 42 --title "Corrected title"
orbit -p myprofile bb pr edit L3SUP agents-sre 42 --description-file pr-body.md
查找内容
# Repos by name, across every project (no project key needed)
orbit -p myprofile bb repo search agentic
orbit -p myprofile bb repo search agentic --project EPCAP --permission REPO_WRITE

# Projects by display name
orbit -p myprofile bb project search "Agentic Platform"

# What a repo is built with: search for the build file, not the name
orbit -p myprofile bb code search go.mod --repos
orbit -p myprofile bb code search build.gradle.kts --repos

# Request changes on a PR (Bitbucket Server NEEDS_WORK). Aliases: request-changes.
# Pair with 'pr comment' to leave the actionable feedback first, then flip the status.
orbit -p myprofile bb pr comment L3SUP agents-sre 42 -m "Please address the items above"
orbit -p myprofile bb pr needs-work L3SUP agents-sre 42

# Decline a PR (closes it — use needs-work for "request changes" instead)
orbit -p myprofile bb pr decline L3SUP agents-sre 42

# Add a comment to a PR
orbit -p myprofile bb pr comment L3SUP agents-sre 42 --body "LGTM!"

# View PR activity (comments, approvals, status changes)
orbit -p myprofile bb pr activity L3SUP agents-sre 42

PR 状态： OPEN、MERGED、DECLINED、ALL

分支和标签
# List branches
orbit -p myprofile bb branch list L3SUP agents-sre

# Filter branches by name
orbit -p myprofile bb branch list L3SUP agents-sre --filter feature

# Show default branch
orbit -p myprofile bb branch default L3SUP agents-sre

# Create a branch from a ref
orbit -p myprofile bb branch create L3SUP agents-sre feature/new-thing main

# Delete a branch
orbit -p myprofile bb branch delete L3SUP agents-sre feature/old-thing

# List tags
orbit -p myprofile bb tag list L3SUP agents-sre

# Create a tag
orbit -p myprofile bb tag create L3SUP agents-sre v1.0.0 main -m "Release v1.0.0"
提交
# List recent commits (default branch)
orbit -p myprofile bb commit list L3SUP agents-sre

# List commits on a specific branch
orbit -p myprofile bb commit list L3SUP agents-sre --branch feature/new

# View commit details
orbit -p myprofile bb commit view L3SUP agents-sre abc1234def5678
用户
# List users
orbit -p myprofile bb user list

# Filter users by name
orbit -p myprofile bb user list --filter john
默认审阅者条件（管理员）

管理项目级默认审阅者条件，这些条件会自动分配审阅者，并在 PR 上强制要求审批。别名：rc。

# List all default reviewer conditions for a project
orbit -p myprofile bb reviewer-condition list EPCAP
orbit -p myprofile bb rc list EPCAP -o json

# Update required approvals (e.g., temporarily set to 0 to bypass)
orbit -p myprofile bb rc update EPCAP 1063 --required-approvals 0

# Restore required approvals
orbit -p myprofile bb rc update EPCAP 1063 --required-approvals 2

# Delete a condition
orbit -p myprofile bb rc delete EPCAP 1063

绕过必需审阅者造成的合并阻止：

当 PR 合并因“并非所有必需审阅者都已批准”而受阻时，这是由项目级默认审阅者条件强制执行的（而非仓库合并钩子）。在 pr merge 上使用 --bypass-review，它会自动处理合并钩子和默认审阅者条件：

orbit -p myprofile bb pr merge EPCAP my-repo 42 --bypass-review

或者手动操作：列出条件以找到阻止合并的条件，将其必需审批数设为 0，完成合并，然后恢复原设置。

常见用法

获取 JSON 以供脚本处理：

orbit -p myprofile bb pr list L3SUP agents-sre -o json | jq '.[].title'

端到端审阅 PR：

# View PR details and reviewers (can run in parallel with activity)
orbit -p myprofile bb pr view L3SUP agents-sre 42
orbit -p myprofile bb pr activity L3SUP agents-sre 42

# Get the full diff for code review (run SEPARATELY, not in parallel)
orbit -p myprofile bb pr diff L3SUP agents-sre 42

# Outcome: approve (all good)
orbit -p myprofile bb pr approve L3SUP agents-sre 42
orbit -p myprofile bb pr comment L3SUP agents-sre 42 --body "LGTM!"

# Outcome: request changes (three issues need fixing before merge)
orbit -p myprofile bb pr comment L3SUP agents-sre 42 --body "Please address: 1) ..., 2) ..., 3) ..."
orbit -p myprofile bb pr needs-work L3SUP agents-sre 42

选择合适的审阅结果：

结果命令使用场景
批准pr approvePR 已准备好合并；没有阻碍。
请求修改pr needs-workPR 需要修复，但整体方向正确。作者处理反馈并推送后，你再改为 approve。PR 会保持开启。
拒绝pr declinePR 从根本上存在问题，不应合并。会关闭 PR；只能通过重新打开来撤销。普通审阅后很少应选择此项——优先使用 needs-work。

从 URL 中提取项目键和仓库 slug： 假设 URL 为 https://git.cnvrmedia.net/projects/L3SUP/repos/agents-sre/pull-requests：

  • 项目键：L3SUP
  • 仓库 slug：agents-sre 然后运行：orbit -p myprofile bb pr list L3SUP agents-sre

检查项目中有哪些仓库：

orbit -p myprofile bb repo list L3SUP

重要说明

  • 不要与其他命令并行运行 pr diff。 diff 端点返回的是原始文本（而非 JSON），可能会干扰基于 JSON 的并行命令。务必按顺序运行 pr diff，切勿在同一个并行 Bash 块中与其他 orbit 命令一起运行。
  • 必须指定配置文件 — 始终传入 -p <profile> 以选择 Bitbucket 连接。该配置文件必须配置了 bitbucket 类型的服务。
  • 服务标志 — 如果一个配置文件有多个 Bitbucket 服务，请使用 --service <name> 以区分。
  • Server 与 Cloud — 配置中的服务变体（server 或 cloud）决定 API 前缀。Server 使用 /rest/api/latest/，Cloud 使用 /2.0/。
  • 密钥引用 - 配置中的凭据可以使用 1Password（op://vault/item/field）或 Infisical（infisical://<env>/<path>/<KEY>）引用，并在运行时解析。运行一次 orbit auth 即可解析并缓存所有密钥（1Password 只需一次生物识别提示）。使用 orbit auth clear 清除缓存。请参阅密钥。
  • PR 状态必须大写 — 使用 OPEN、MERGED、DECLINED 或 ALL（输入时不区分大小写）。
  • 分页 — 大多数列表命令默认返回 25–50 条结果。使用 --limit N 调整数量。
  • URL 解析 — 用户提供类似 https://host/projects/KEY/repos/SLUG/... 的 Bitbucket Server URL 时，请从 URL 路径中提取项目键和仓库 slug，以用于 orbit 命令。

评论

支持 Markdown