gh のように使える Bitbucket CLI ワークフロー

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

Bitbucket に空いた gh 型の穴

GitHub の gh を使ったことがあると、Bitbucket に移ったときに大きな喪失感があります。gh pr create、gh pr list、gh pr merge と打つのが体に染みついているのに、Bitbucket ではその反射が空振りします。開発者からよく挙がる要望は短く具体的で、gh のような Bitbucket CLI が欲しい、しかし期待どおりに動くものが見つからない、というものです。

結論から言うと、gh を 1 対 1 で再現する Atlassian 提供のコマンドはありませんが、atlassian-cli を使えば同じ gh 風のワークフローを今すぐ実現できます。MIT ライセンスの独立した Rust バイナリで、Bitbucket Cloud の REST API と通信するため、プルリクエストの一覧表示、作成、レビュー、マージがすべてターミナルから行えます。ブラウザのタブを開く必要は一切ありません。この記事では、すでに慣れている gh pr と gh repo の各コマンドを atlassian-cli の対応するコマンドに対応づけ、手になじむようにエイリアスを設定する方法を紹介します。

acli との違い

Bitbucket の CLI を検索すると両方のツールが出てくるため、この違いは重要です。Atlassian の acli はベンダーがサポートする選択肢で、正式なサポート保証が必要な場合はこちらが適しています。atlassian-cli は、gh の使い心地を気に入っていて、その操作感を Atlassian のスタック全体に 1 つのバイナリで広げたい人のためのコミュニティ製の選択肢です。この記事の残りは 2 つ目の道について書いています。

gh から atlassian-cli へのコマンド対応表

対応表は次のとおりです。どのコマンドも、atlassian-cli auth login で一度認証を済ませていることを前提としています（認証ガイドを参照）。bb エイリアスは bitbucket の組み込みの短縮形なので、atlassian-cli bb pr list と atlassian-cli bitbucket pr list は同じ意味になります。

構造上の違いが 1 つあります。gh はローカルの git リモートからリポジトリを推測しますが、atlassian-cli は --workspace とリポジトリスラッグを明示的に求めます。これはスクリプトから扱いやすくするための意図的なトレードオフで、後述のエイリアスを使えば手で入力する場面はほとんどなくなります。

最初の gh 風 PR ワークフロー

定番の流れをたどってみます。ブランチを作り、プッシュし、PR を作成し、レビューを受けてマージするという流れです。ワークスペースは myteam、リポジトリスラッグは api-service とします。

プルリクエストを作成する

ブランチは通常どおり git でプッシュし、PR は CLI から作成します。これが gh pr create に直接対応します。

# Push your feature branch the normal way
git push -u origin feature/new-endpoint

# Open the PR against main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add /v2/orders endpoint" \
  --source feature/new-endpoint \
  --destination main

オープンな PR の一覧表示と確認

gh pr list と gh pr view に相当します。どのコマンドにも --format json を付ければ jq にパイプできます。

# List open PRs (gh pr list)
atlassian-cli bb --workspace myteam pr list api-service --state OPEN --limit 5

# Inspect one PR by id (gh pr view 123)
atlassian-cli bb --workspace myteam pr get api-service 123

# Pull just the titles and authors with jq
atlassian-cli bb --workspace myteam pr list api-service --state OPEN \
  --format json | jq '.[] | {id, title}'

レビュー、コメント、マージ

承認、コメント、マージで一連の流れが完成します。マージ戦略には merge_commit のように Bitbucket が用意している値をそのまま指定できます。

# Approve the PR (gh pr review --approve)
atlassian-cli bb --workspace myteam pr approve api-service 123

# Leave a review comment (gh pr comment)
atlassian-cli bb --workspace myteam pr comment api-service 123 \
  --text "Ship it once CI is green."

# Merge it (gh pr merge 123)
atlassian-cli bb --workspace myteam pr merge api-service 123 --strategy merge_commit

作成からマージまで、gh 風の流れはこれで一通りです。Bitbucket をブラウザで開く必要は一度もありません。この流れをスケジュール実行や CI から動かす場合は、Bitbucket PR 自動化ランブックにそのまま応用できるスクリプトがあります。

エイリアスとラッパーで gh に近づける

素のコマンドで面倒なのは繰り返しです。行ごとに --workspace myteam とリポジトリスラッグを書く必要があります。gh は git リモートを読むことでこれを回避しています。現在の git リポジトリからスラッグを推測し、ワークスペースを補う小さなシェル関数を用意すれば、ほぼ同じところまで持っていけます。.zshrc か .bashrc に次を追加してください。

# gh-style Bitbucket wrapper: PR verb first, repo slug from the git remote
export BB_WORKSPACE="myteam"

bbpr() {
  # First argument is the PR verb (list, get, create, approve, merge, ...)
  local verb="$1"; shift
  # Extract the repo slug from the origin remote URL
  local slug
  slug=$(git remote get-url origin 2>/dev/null \
    | sed -E 's#.*[/:]([^/]+/)?([^/]+?)(\.git)?$#\2#')
  atlassian-cli bitbucket --workspace "$BB_WORKSPACE" pr "$verb" "$slug" "$@"
}

atlassian-cli は --format json できれいな JSON を出力するため、gh のまわりで使われている工夫はそのまま移植できます。PR の一覧を fzf にパイプして対話的に選んだり、jq に渡して出力を整形したり、CI の通知スクリプトに流し込んだりできます。出力形式はコマンドリファレンスにすべて記載されています。table、json、csv、yaml、quiet、markdown が使えます。

gh と正直に違う点

gh 風のワークフローは gh のクローンではありません。後で驚かないよう、違いをはっきりさせておきます。

• pr checkout がない。atlassian-cli は API クライアントであり、git のラッパーではありません。gh pr checkout のように作業コピーのブランチを切り替えることはしません。ローカルでは git fetch と git switch をそのまま使い、サーバー側の操作に atlassian-cli を使います。
• ワークスペースとスラッグの明示が必要。gh が git リモートを読むのに対して、atlassian-cli は --workspace とリポジトリスラッグを求めます。上のラッパーでその差はほぼ埋められます。
• 1 つのバイナリで複数の製品。その代わり、PR を作成するのと同じツールで、リンクされた Jira 課題を遷移させたり、Confluence のリリースノートを更新したりできます。gh は GitHub 専用ですが、atlassian-cli は Atlassian のスタック全体をカバーします。

どれもターミナル中心のワークフローにとって致命的なものではありません。API 駆動のツールである以上、避けられないコストであり、多くの Bitbucket ユーザーにとっては差し引きで明らかにプラスになります。

リポジトリ、ブランチ、パイプラインへ広げる

gh で身についた操作感はプルリクエストの外にも広がります。リポジトリ管理とブランチ管理はきれいに対応づけられますし、Bitbucket Pipelines にいたっては gh が標準ではまったくカバーしていない領域です。

# Repos: list, inspect, create (gh repo list / view / create)
atlassian-cli bb --workspace myteam repo list --limit 10
atlassian-cli bb --workspace myteam repo get api-service
atlassian-cli bb --workspace myteam repo create newrepo --name "New Repo" --private

# Branches: list, create, protect
atlassian-cli bb --workspace myteam branch list api-service
atlassian-cli bb --workspace myteam branch create api-service feature/new --from main
atlassian-cli bb --workspace myteam branch protect api-service \
  --pattern "main" --kind restrict_merges --approvals 2

# Pipelines: trigger a build straight from the terminal
atlassian-cli bb --workspace myteam pipeline trigger api-service --ref-name main

古いブランチやリポジトリを一括で整理する用途には、ドライランで安全に確認できる一括操作コマンドが用意されています（たとえば bb --workspace myteam bulk delete-branches api-service --dry-run）。詳しい手順はブランチ整理ランブックを、コマンドの全体像は Bitbucket CLI ハブを参照してください。

よくある質問

関連リソース