Bitbucket のプルリクエストレビューとチェックを自動化する

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

Bitbucket のプルリクエストレビューを自動化する理由

Bitbucket PR のレビューサイクルは、ブラウザのタブを一度も開かずにすべてターミナルから進められます。オープンなプルリクエストの一覧表示、承認者の確認、レビューコメントの追加、承認、マージチェックの確認、そしてマージまでです。以下では、atlassian-cli の具体的なコマンドと、レビュー未了のブランチが通り抜けないように継続的インテグレーションへ組み込む方法を紹介します。

レビュー作業はもともと反復的です。レビュアーはプルリクエストの一覧を開き、オープンなものに絞り込み、差分を読み、コメントを残し、Approve をクリックし、最後にマージします。これが十数個のリポジトリと忙しいチームに広がると、クリックの回数は積み上がります。さらに厄介なのは、「このプルリクエストはマージ前に十分な承認と成功したビルドがそろっているか」という重要なガードレールが、急いでいると目視で判断を誤りやすいことです。これらの手順をコマンドラインに移すと、スクリプト化でき、再現性があり、CI でテストできるようになります。CI ではチェックの失敗がマージを止めるので、誰かの記憶に頼らずに済みます。

Atlassian の acli との違い

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要な場合は acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、どこでも同じフラグと出力形式が使える無料の単一 Rust バイナリが欲しい場合は atlassian-cli を使ってください。以下ではすべて bitbucket コマンドグループ（短いエイリアスは bb）を使います。どのコマンドもグローバルな --format と --profile フラグを受け付けるため、CI でのスクリプト化が予測しやすくなります。

すべてのコマンドは --workspace とリポジトリのスラッグを取ります。以降は myteam をご自身の Bitbucket ワークスペース ID に、api-service をご自身のリポジトリのスラッグに読み替えてください。123 のような数値の ID はプルリクエストの ID です。

オープンなプルリクエストの一覧と確認

どのレビューも同じ問いから始まります。何がオープンで、何が待たされているのか。pr list コマンドは state と limit で絞り込めます。

# All open PRs in a repo, newest activity first
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 20

# Machine-readable, so a script can loop over IDs
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --format json \
  | jq '.[] | {id: .id, title: .title, author: .author.display_name}'

1 件のプルリクエストを詳しく読むには、その ID を pr get に渡します。既定の出力は読みやすい要約です。特定のフィールドをプログラムから取り出したい場合は --format json を追加します。

# Human-readable PR summary
atlassian-cli bitbucket --workspace myteam pr get api-service 123

# Full JSON payload for scripting
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json

この JSON ペイロードが、以降のすべてのチェックの材料になります。Bitbucket Cloud はプルリクエストの state（OPEN、MERGED、DECLINED）、author、ソースとマージ先のブランチ、そして participants 配列を返します。各参加者は role（REVIEWER または PARTICIPANT）、approved のブール値、ユーザーの詳細を持ちます。これがそのまま、まだレビューを返していないのは誰かを判断する材料になります。

同じ --format json フラグがすべてのコマンドで使えるため、特別な連携なしにリポジトリ横断のレビューダッシュボードを作れます。リポジトリをループし、それぞれで pr list を実行し、オープンなプルリクエストをひとつのレポートにまとめるだけです。Web UI は一度にひとつのリポジトリしか扱えないためこれが面倒になりますが、3 行のシェルループなら簡単に片づきます。

ターミナルから承認とコメントを行う

差分を読み終えたあとに最もよく使うレビュー操作は、承認とコメントの 2 つです。どちらも 1 行で済みます。

# Approve the pull request (same as clicking Approve in the UI)
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

# Leave a written review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Logic looks good. Please add a test for the empty-input case before merge."

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

よくあるパターンは、コメントしてから承認する流れです。フィードバックを投稿し、それがブロッカーでなければ続けて承認しておくと、作成者が次のラウンドを待たずに済みます。pr comment はフラグでプレーンテキストを受け取るので、テンプレートや Linter の出力からメッセージを組み立てて自動投稿できます。CLI がプルリクエスト向けに提供するレビュー操作は次のとおりです。

承認状況とマージ可否を確認する

レビューを自動化する狙いは、マージできるかどうかを主観的な判断ではなくデータの問題にすることです。pr get --format json は participants 配列を返すので、jq で承認数を数え、そのプルリクエストが基準を満たすかどうかを判断できます。

# How many reviewers have approved?
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '[.participants[] | select(.approved == true)] | length'

# Who still needs to approve?
atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '.participants[] | select(.role == "REVIEWER" and .approved == false) | .user.display_name'

この件数を小さなチェックで包めば、どこでも実行できるマージゲートになります。--format quiet フラグもここで役立ちます。出力を抑えるので、スクリプト内の && による分岐をコマンドの終了コードだけで制御できます。

# Fail the script unless the PR has at least 2 approvals
APPROVALS=$(atlassian-cli bitbucket --workspace myteam pr get api-service 123 --format json \
  | jq '[.participants[] | select(.approved == true)] | length')

if [ "$APPROVALS" -lt 2 ]; then
  echo "Blocked: only $APPROVALS approval(s), need 2" >&2
  exit 1
fi
echo "OK: $APPROVALS approvals"

これで「十分な人数がレビューしたか」が厳密なチェックになります。マージ前にローカルで実行しても、マージ先ブランチを守るパイプラインの中で実行しても、ロジックは同じです。

ブランチのルールで必要な承認数を強制する

スクリプトによるチェックは有効な備えですが、最も強い保証は Bitbucket 自身が与えてくれます。ブランチ制限はリポジトリ側に設定され、保護対象のブランチを狙うすべてのプルリクエストにサーバー側で適用されるため、誰も迂回してマージできません。atlassian-cli では branch protect で管理します。

# Require 2 approvals before anything merges into main
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" \
  --kind restrict_merges \
  --approvals 2

# Review the restrictions currently in force
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

このルールがあれば、pr merge コマンドも、Web UI も、ほかの誰も同じ基準に従います。main を対象とするプルリクエストには 2 件の承認が必要で、そろわなければマージできません。CLI で一度ルールを設定しておけば、セットアップスクリプトにコミットして、ワークスペース内のすべてのリポジトリに同じポリシーを適用できます。リポジトリごとに設定画面をクリックして回る必要はありません。

戦略を選んでマージする

チェックが通ったらマージします。pr merge コマンドは --strategy フラグを受け取るので、自動化をマージ先ブランチの履歴方針に合わせられます。

# Standard merge commit
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

# Squash all commits into one, common for a clean main history
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy squash

Bitbucket Cloud は 3 つのマージ戦略に対応しています。merge_commit はすべてのコミットを残してマージコミットを追加し、squash はブランチをひとつのコミットにまとめ、fast_forward はマージコミットを作らずにブランチのポインターを進めます。前の節のブランチルールを満たしていない場合、マージは拒否されます。これはまさに求めていた安全策です。スクリプトで戦略を統一しておけば、UI のドロップダウンで起きがちな「どのボタンを押したか」というばらつきもなくなります。

パイプラインの中でマージを制御する

これらを組み合わせると、Bitbucket Pipelines でも任意の CI ランナーでも実行できる、自己完結したゲートになります。以下のスクリプトはプルリクエストがオープンであることを確認し、承認数を数え、基準を満たしたときだけマージします。

#!/bin/bash
# auto-merge.sh: merge a PR only when it is open and has enough approvals
set -euo pipefail

WORKSPACE="myteam"
REPO="api-service"
PR="$1"
REQUIRED=2

PR_JSON=$(atlassian-cli bitbucket --workspace "$WORKSPACE" pr get "$REPO" "$PR" --format json)

STATE=$(echo "$PR_JSON" | jq -r '.state')
if [ "$STATE" != "OPEN" ]; then
  echo "PR $PR is $STATE, nothing to do"
  exit 0
fi

APPROVALS=$(echo "$PR_JSON" | jq '[.participants[] | select(.approved == true)] | length')
if [ "$APPROVALS" -lt "$REQUIRED" ]; then
  echo "Blocked: $APPROVALS/$REQUIRED approvals" >&2
  exit 1
fi

atlassian-cli bitbucket --workspace "$WORKSPACE" pr merge "$REPO" "$PR" --strategy squash
echo "Merged PR $PR after $APPROVALS approvals"

Bitbucket のアプリパスワードまたは API トークンを保持する --profile でランナーを一度認証しておけば（認証ガイドを参照）、スクリプトに対話入力は不要です。先ほどのサーバー側のブランチルールと組み合わせれば多層防御になります。パイプラインは承認なしにマージを呼び出さず、Bitbucket も条件を満たさないマージを拒否します。ログ出力や確認プロンプトを備えた、より長い実運用向けの版は Bitbucket プルリクエスト自動化ランブックをご覧ください。CI のビルド結果もこのゲートに取り込みたい場合は、関連記事の CLI から Bitbucket Pipelines を起動するで、マージ前にパイプラインを実行して監視する方法を解説しています。

よくある質問

関連リソース