CLI から Bitbucket のプルリクエストを作成・マージする

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

CLI でのプルリクエストの流れ

コマンドラインから Bitbucket プルリクエストを作成するには、atlassian-cli bitbucket pr create にリポジトリスラッグ、タイトル、ソースブランチ、宛先ブランチを指定して実行します。マージするときは atlassian-cli bitbucket pr merge に PR の ID とマージ戦略を指定します。その間にあるオープンな PR の一覧表示、差分の確認、承認、コメントも、それぞれ 1 つのサブコマンドで行えます。

プルリクエストをターミナルから操作する価値は、文脈が途切れないことにあります。すでにリポジトリの中にいて、ブランチ上にいて、コミットの内容も頭に残っています。そこでブラウザに切り替え、PR ページの表示を待ち、フォームを埋め、レビューのメニューをクリックして回ると、その流れが途切れます。atlassian-cli なら、ライフサイクル全体がシェルの中で完結するため、スクリプト化やエイリアス化、Git フックへの組み込みもできます。

このガイドでは、1 つの PR に対する日々のワークフロー、つまり作成、一覧表示、レビュー、マージを順に見ていきます。多数の PR をスケジュールで一括承認・マージする無人スクリプトが必要な場合は用途が異なり、Bitbucket PR 自動化ランブックで扱っています。ここでは開発者が手で実行する対話的なコマンドに焦点を当てます。

認証とワークスペースの設定

Bitbucket のコマンドには、プロファイルに保存したトークンと、対象となるワークスペースが必要です。auth login で一度認証し、whoami で認証情報が解決されることを確認します。

# Store credentials in a named profile (one time)
atlassian-cli auth login \
  --profile work \
  --base-url https://api.bitbucket.org \
  --email you@example.com \
  --token $BITBUCKET_TOKEN \
  --default

# Confirm the Bitbucket token resolves
atlassian-cli bitbucket whoami

すべての Bitbucket コマンドは --workspace フラグを受け取り、リポジトリを所有するチームまたはアカウントを指定します。リポジトリ自体は位置引数のスラッグ、つまりリポジトリ URL に含まれる短い名前として渡します。毎回 bitbucket と打つのが長いと感じるなら、bb エイリアスがまったく同じ働きをします。atlassian-cli bb whoami も同じ結果になります。トークンのスコープや複数アカウントの設定は認証とプロファイルのガイドを参照してください。

複数の Bitbucket アカウントを使い分けている場合は、それぞれを別のプロファイルに保存し、任意のコマンドに --profile <name> を付けて切り替えます。仕事用と個人用のアカウントが混ざることがなくなり、間違ったワークスペースに PR を作ってしまうというよくあるミスも防げます。フラグを省略したときは --default を付けたプロファイルが使われるため、もっともよく使うアカウントを既定にし、例外のときだけ --profile を指定するとよいでしょう。

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

pr create コマンドには、リポジトリスラッグと 3 つのフラグが必要です。--title、--source（作業したブランチ）、--destination（通常は main）です。

# Open a PR from feature/new into main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add retry logic to the S3 client" \
  --source feature/new \
  --destination main

コマンドは新しいプルリクエストの ID を返し、以降の操作ではこの ID を使います。ソースブランチがまだ存在しない場合は、CLI から離れずに先に作成できます。

# Cut a branch from main, then open the PR against it
atlassian-cli bitbucket --workspace myteam branch create api-service feature/new --from main

スクリプトから PR の ID を取得するために生のレスポンスが欲しい場合は、グローバルな --format json フラグを付けて jq にパイプします。

# Capture the new PR id into a shell variable
PR_ID=$(atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add retry logic" \
  --source feature/new \
  --destination main \
  --format json | jq '.id')

ID をプログラムから取得できるため、作成をそのまま後述のレビューとマージの手順につなげられます。これがこの記事の後半に出てくる完全な例の骨組みになります。

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

重複した PR を作る前に、あるいはレビューする対象を選ぶ前に、すでにオープンな PR を一覧表示します。pr list コマンドはステータスで絞り込み、取得件数の上限も指定できます。

# Show the five most recent open PRs
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 5

# As JSON for scripting or dashboards
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --format json

ID が分かれば、pr get でタイトル、説明、ソースブランチと宛先ブランチ、作成者、レビュアー、現在の承認状況といった詳細をすべて確認できます。

# Inspect a single pull request
atlassian-cli bitbucket --workspace myteam pr get api-service 123

--state フィルターは Bitbucket 標準の値（OPEN、MERGED、DECLINED、SUPERSEDED）を受け付けるため、同じコマンドが監査ツールとしても使えます。たとえばスプリント期間の MERGED な PR を一覧表示すれば、Web UI を開かずに変更履歴の材料が手早く得られます。

承認、コメント、更新

PR のレビューは 3 つのサブコマンドで行えます。既存のコメントスレッドを読み、自分のコメントを追加し、承認を記録します。いずれもリポジトリスラッグと PR の ID を取ります。

# Read the existing comment thread
atlassian-cli bitbucket --workspace myteam pr comments api-service 123

# Leave a review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Nice fix. Can you add a test for the timeout path?"

# Record an approval
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

レビューの途中でタイトルやスコープが変わった場合は、却下して作り直さなくても pr update でその場で編集できます。

atlassian-cli bitbucket --workspace myteam pr update api-service 123 \
  --title "Add retry logic and timeout handling to the S3 client"

これらのコマンドは Bitbucket のレビュー画面のボタンに 1 対 1 で対応するため、承認の仕組み自体は変わりません。変わるのは、レビュアーが 10 件の PR を 10 回のページ読み込みではなく 10 個の短いコマンドで承認できるという点です。

プルリクエストをマージする

必要な承認がそろったら、pr merge で完了させます。リポジトリスラッグ、PR の ID、--strategy フラグを渡します。

# Merge PR 123 with a merge commit
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

CLI からのマージは、設定した制御を回避するものではありません。Bitbucket API は宛先ブランチに設定されたブランチ制限や必要承認数のルールを引き続き適用するため、承認数を満たしていない PR はサーバー側で拒否され、強制的にマージされることはありません。main を保護していれば、どこからマージを実行してもその保護は有効です。マージ前に branch restrictions api-service でルールを確認できます。

--strategy フラグは Bitbucket Cloud API が対応する 3 つのマージ戦略を受け付けます。リポジトリのポリシーに合うものを選んでください。

宛先ブランチが分岐している場合は fast_forward が使えず、API はエラーを返します。これはバグではなく、想定された安全のための動作です。その場合は merge_commit か squash に切り替えてください。

作成からマージまでの完全な例

ライフサイクル全体をひとつなぎにした例です。頻繁にリリースするリポジトリ向けに、シェル関数として手元に置いておくとよいでしょう。

#!/bin/bash
# Create, self-approve as reviewer, and merge a PR end to end
set -euo pipefail

WS="myteam"
REPO="api-service"
SRC="feature/new"

# 1. Open the PR and capture its id
PR_ID=$(atlassian-cli bitbucket --workspace "$WS" pr create "$REPO" \
  --title "Add retry logic to the S3 client" \
  --source "$SRC" \
  --destination main \
  --format json | jq '.id')

echo "Opened PR #$PR_ID"

# 2. Show it for a final human check
atlassian-cli bitbucket --workspace "$WS" pr get "$REPO" "$PR_ID"

# 3. Record an approval
atlassian-cli bitbucket --workspace "$WS" pr approve "$REPO" "$PR_ID"

# 4. Merge with a squash so main stays linear
atlassian-cli bitbucket --workspace "$WS" pr merge "$REPO" "$PR_ID" --strategy squash

echo "Merged PR #$PR_ID"

手順 2 では PR を表示して、スクリプトが先に進む前に人が目視できるようにしています。この行を削れば完全に非対話的な流れになり、そこから自動化ランブックの領域と重なってきます。確認プロンプト、レビュアーの割り当て、多数のリポジトリにまたがるエラー処理まで含めた堅牢な版は、Bitbucket PR 自動化ランブックを参照してください。リポジトリ、ブランチ、パイプラインに関して CLI でできることは、Bitbucket CLI ハブがリファレンスになります。

acli との違い

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。Atlassian が提供する公式 CLI（acli）ではありません。ベンダーによる一次サポートが必要な場合は公式の acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を一貫したコマンド体系で 1 つの無料の Rust バイナリから扱いたい場合は atlassian-cli が向いています。

プルリクエストにおける実際的な利点は、pr create、pr list、pr approve、pr merge の各コマンドが Jira や Confluence の対応するコマンドと同じ読み方になり、グローバルな --format json、--profile、--workspace のフラグがどこでも同じように動くことです。すでにターミナルから Jira を操作しているなら、Bitbucket まわりで新しく覚える考え方はありません。コマンドの全一覧はコマンドリファレンスに、リポジトリ、ブランチ、パイプラインのコマンドをより広く紹介した記事は Bitbucket CLI ガイドにあります。

よくある質問

関連リソース