bitbucket

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]

すべてのコマンドで JSON 出力用の -o json を使用できます。コマンドの詳細とすべてのフラグについては、references/commands.md を参照してください。

セルフホストのインスタンスで自己署名証明書を使用する場合は、サービス設定に tls_skip_verify: true を追加してください。プロキシ経由でアクセスするには、proxy: socks5://host:port を追加してください。

アドレス指定規則

Bitbucket Server/Data Center では、リポジトリの識別に プロジェクトキー + リポジトリスラッグ を使用します。ほとんどのコマンドで必要となる位置引数は、この 2 つです。

• プロジェクトキー： 大文字の短いコード（例：L3SUP、MYPROJ）
• リポジトリスラッグ： 小文字とハイフンを使った名前（例：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 では GitHub と同様に、「プルリクエスト」（PR）を使用します。

# 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

必須レビュアーによるマージブロックを回避する：

「Not all required reviewers have approved yet（必須レビュアー全員の承認がまだ得られていません）」という理由で 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 approve	PR はマージ可能な状態で、ブロッカーがありません。
変更をリクエスト	pr needs-work	PR に修正が必要ですが、方向性は適切です。作成者がフィードバックに対応してプッシュしたら、approve に変更します。PR はオープンのままです。
却下	pr decline	PR の根本的な方針が誤っており、マージすべきではありません。PR をクローズします。再オープンによってのみ取り消せます。通常のレビュー後に適切な選択となることはまれです。needs-work を優先してください。

URL からプロジェクトキーとリポジトリスラッグを取得する： https://git.cnvrmedia.net/projects/L3SUP/repos/agents-sre/pull-requests の場合：

• プロジェクトキー：L3SUP
• リポジトリスラッグ：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 は必ず順次実行してください。ほかの orbit コマンドと同じ並列 Bash ブロック内では実行しないでください。
• プロファイルが必須です — Bitbucket 接続を選択するには、常に -p <profile> を渡してください。プロファイルには、タイプが 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 の生体認証プロンプトは 1 回だけ表示されます）。キャッシュを消去するには orbit auth clear を使ってください。シークレットを参照してください。
• PR の状態は大文字です — OPEN、MERGED、DECLINED、ALL のいずれかを使ってください（大文字と小文字を区別しない入力も受け付けます）。
• ページネーション — ほとんどの一覧コマンドでは、結果のデフォルト件数は 25～50 件です。件数を調整するには --limit N を使ってください。
• URL の解析 — ユーザーから https://host/projects/KEY/repos/SLUG/... のような Bitbucket Server の URL が提供された場合は、URL パスからプロジェクトキーとリポジトリのスラッグを抽出し、orbit コマンドで使用してください。