Claude Media
Claude CodeにMergify CLIを入れてマージキューとスタックPRを操作する
Claude Codeチュートリアル

Claude CodeにMergify CLIを入れてマージキューとスタックPRを操作する

Mergify CLIの導入、auth loginとMERGIFY_TOKENの優先順位、キュー停止やquarantineをClaude Codeに任せない権限設定までをまとめます。

読了目安 約16分

Mergify CLIは、マージキュー、スタックPR、CI Insights、スケジュール凍結を端末から操作する単一バイナリです。Claude Codeには公式マーケットプレイスにMergifyのプラグインがあり、CLIの使い方をスキルとして渡せます。

ただ、CLIには「キューを止める」「テストを隔離する」のようにチーム全体へ効く操作が含まれます。Claude Codeに触らせる範囲を先に決めておくと、導入が安全に進みます。この記事は、導入から資格情報の扱い、権限ルール、CLAUDE.mdへの書き方までを順に扱います。

CLI本体とプラグインは別物として入れる

Mergify CLIの本体は、実行環境に依存しない単一の静的バイナリです。入れ方はOSで分かれます。

  • macOS: brew install mergifyio/tap/mergify-cli
  • Linux(macOSも可): インストールスクリプトで ~/.local/bin/mergify に配置
  • Windows: リリースのzipを展開し、mergify.exe をPATHの通った場所に置く
brew install mergifyio/tap/mergify-cli
mergify --help

Homebrewで入れた場合の更新は brew upgrade mergify-cli です。mergify self-update はHomebrew管理のバイナリを上書きするため使いません。スクリプトで入れた場合は mergify self-update で更新できます。スクリプトは MERGIFY_INSTALL_DIR で配置先を、MERGIFY_VERSION でバージョンを指定できます。

Claude Code側には、プラグインとスキルの2つの入れ方があります。

/plugin install mergify@claude-plugins-official

プラグインの説明ページには、マージキュー、スタックPR、Test Insights(不安定テストとquarantine)、マージ保護、Mergify設定をターミナルから扱うスキル、とあります。Claude Codeを含む複数のエージェントに入れるなら、npx skills add Mergifyio/mergify-cli も案内されています。

プラグインが入れるのは、CLIの使い方を教えるスキルです。mergify コマンド自体は上の手順で別に用意します。コマンドが無いまま依頼すると、Claude Codeは存在しないバイナリを呼んで失敗します。インストールの順序は「CLI本体、認証、プラグイン」にそろえておくと迷いません。

プラグインの導入範囲は、個人だけにするかリポジトリ全体にするかを選べます。チームで揃えるなら、プロジェクトスコープで .claude/settings.json に記録します。ただしその記録は有効化の設定であり、各メンバーの手元へのダウンロードは別です。各自が claude plugin install mergify@claude-plugins-official --scope project を一度実行する必要があります。

認証は「誰の資格情報で動くか」を決めてから始める

人が使う場合は mergify auth login が基本です。ブラウザで承認すると、資格情報がOSのキーチェーンに入ります。キーチェーンが無い環境(コンテナ、無人エージェント、D-Busセッションの無いヘッドレス機)では、設定ディレクトリ配下の制限付きファイルに保存されます。

ブラウザを開けない場所では --no-browser を付けます。URLとコードが表示されるので、別の端末で承認します。承認ページに出るトークン名は「Mergify CLI onホスト名」です。--device-name "work laptop" で名前を付けられ、--device-name= と空にすればホスト名を送りません。

Mergify APIを呼ぶコマンドは、次の順に資格情報を探します。

順位資格情報備考
1資格情報--token / -t備考コマンドごとの明示指定
2資格情報MERGIFY_TOKEN備考CIではこれを使う
3資格情報mergify auth login が保存した資格情報備考API URLごとに保存
4資格情報GITHUB_TOKEN備考非推奨
5資格情報gh auth token備考非推奨

4と5のGitHubトークンは、今はMergify APIに通りますが、実行のたびに非推奨の警告が出ます。READMEは将来のリリースで使えなくなると明記しています。mergify auth login に移すのが筋です。

保存した資格情報は mergify auth status で確認できます。mergify auth logout は、ローカルの削除だけでなくMergify側の失効まで行います。

Claude Codeの作業環境で環境変数を使う場合

MERGIFY_TOKEN を環境に置くと、保存済みの資格情報より優先されます。ログイン済みなのに別のトークンで動いている、という食い違いは、まずこの変数を疑います。

例外が2つあります。

  • mergify ci 系は3番(保存資格情報)を使いません。組織のアプリケーションキーが必要で、auth login で発行される個人の資格情報は仕様として拒否されます
  • mergify stack はGitHub APIを直接呼ぶため、GitHubトークンを別に探します。順序は --token、MERGIFY_TOKEN、GITHUB_TOKEN、gh auth token です。Mergifyが発行したトークン(mut_ で始まる)はGitHubに送っても401になるため、読み飛ばされます

アプリケーションキーには ci と admin の2種類があり、片方がもう片方を含む関係ではありません。トレースのアップロードと ci scopes-send は ci キー専用で、adminキーや個人の資格情報では403になります。逆に、テストの健全性の参照(mergify tests show)とquarantineの変更は、adminキーか個人の資格情報が必要で、ci キーは403です。GitHub Actionsの GITHUB_TOKEN は一時的なインストールトークンであり、Mergify APIには届きません。

Claude Codeに任せる操作を権限ルールで分ける

CLIのコマンドは、読むだけのものと、状態を変えるものに分けられます。Claude Codeの権限ルールは、拒否、確認、許可の順に評価され、最初に一致したものが結果を決めます。許可ルールで、拒否ルールの例外は作れません。この順序を使って、危険な操作を確実に止めます。

次は .claude/settings.json の一例です。分類は公式の既定ではなく、コマンドの説明文から読み取った例です。

{
  "permissions": {
    "allow": [
      "Bash(mergify queue status *)",
      "Bash(mergify queue show *)",
      "Bash(mergify stack list *)",
      "Bash(mergify tests show *)",
      "Bash(mergify config validate *)",
      "Bash(mergify auth status *)"
    ],
    "ask": [
      "Bash(mergify stack push *)",
      "Bash(mergify stack sync *)"
    ],
    "deny": [
      "Bash(mergify queue pause *)",
      "Bash(mergify queue unpause *)",
      "Bash(mergify tests quarantines add *)",
      "Bash(mergify tests quarantines remove *)",
      "Bash(mergify auth logout *)"
    ]
  }
}

分けた理由は次のとおりです。

権限設計

操作ごとの扱いの根拠

  • 許可: 状況を読むだけ

    queue status はキュー内のPRの順位と状態を一覧し、queue show は1つのPRについてチェックと未達の条件を返します。どちらも状態を変えません。

  • 確認: 他人の目に見える変更

    stack push は各コミットをブランチへ送り、GitHub上のPRを作成・更新します。stack sync は最新のトランクを取り込み、マージ済みのコミットを外してリベースします。意図しないときの影響が大きいため、毎回確認にします。

  • 拒否: チーム全体に効く

    queue pause はキューのマージを止めます。理由が必須で、チームに表示されます。quarantineへの追加は、そのテストの失敗がマージキューを止めなくなる操作です。人が判断する領域として拒否にします。

拒否ルールは、Claudeが通常書く形のコマンドを止めるためのものです。別の呼び方まで封じる境界ではない点は、権限の公式説明が明記しています。厳密に守りたい操作は、トークンの権限側でも絞ってください。Claude Code側の細かい書き方は権限ルールをパラメータで書く方法にまとめています。

なお queue pause は非対話のセッションで --yes-i-am-sure を要求します。確認プロンプトを飛ばすフラグなので、エージェントに使わせる設計にはしないほうが安全です。

マージキューを読ませる

読み取りは任せやすい領域です。mergify queue status は現在のキューを一覧し、--branch でブランチを絞り、--json でAPIの生の応答を1つのJSONとして出します。ログはstderrに出るので、標準出力はそのままパイプに渡せます。

mergify queue status --json
mergify queue show 1234 --verbose

queue show の --verbose は、チェック表と条件のツリーを全部出します。PRがなぜマージ可能でないのかを、条件単位で追えます。ここまで出力させれば、Claude Codeは「どのチェックが未達か」を根拠付きで説明できます。引数はPR番号1つです。

依頼の例は次のとおりです。

queue showで#1234の状態を出して、マージされない理由を条件ごとに説明して。
キューの操作は実行しないで。

スタックPRを作る

スタックPRは、1コミットを1PRにして、互いの依存関係を保つ運用です。CLIの mergify stack には16個のコマンドがあります。最短の流れは3つです。

mergify stack setup     # リポジトリごとに一度。gitフックを入れる
mergify stack push      # コミットを送り、PRを作成・更新する
mergify stack list      # スタックとPRの状態を見る

stack setup は、コミットにChange-Idのトレーラーを付けるgitフックを入れます。このIDでコミットとPRを結び付けるため、最初に一度だけ実行します。push は、必要ならトランクにリベースし、各コミットを専用ブランチに送ります。PRと Depends-On の連なりも作成・更新します。

実行前に確かめたいときは --dry-run が使えます。計画とリベースの判断だけを表示し、何も変更しません。stack sync と stack drop も同じフラグを持ちます。Claude Codeに依頼するときは、まず --dry-run の結果を読ませてから本実行に進む運用が合います。

つまずきやすい点

落とし穴

stackにはGitHubのトークンが要る

mergify auth login を済ませても、stack はGitHub APIを直接呼びます。GITHUB_TOKEN か gh のログインが必要です。MERGIFY_TOKENにMergify発行のトークンだけを置いている環境では、GitHub向けの資格情報として使われません。

テストの健全性を調べ、隔離は人が決める

mergify tests show <テスト名> は、名前(globも可)でテストを探し、不安定さ、失敗率、直近の履歴を返します。--pipeline-name や --job-name で範囲を絞れ、--json で機械可読にできます。この参照には、adminキーか個人の資格情報が必要です。

隔離は mergify tests quarantines add --reason <理由> <テスト名> です。理由が必須で、--branch で特定のブランチに限れます。指定しないと全ブランチが対象になります。一覧は quarantines list、取り消しは remove です。

Claude Codeには、tests show で候補を調べさせ、隔離の提案文までを書かせる使い方が向いています。追加そのものは、上の権限設定のとおり人が実行します。

CLAUDE.mdに書く規約

権限は「できること」を決め、CLAUDE.mdは「どう振る舞うか」を決めます。CLIの終了コードは固定されているので、失敗時の分岐をそのまま書けます。

## Mergify CLI
- 読み取りは --json を付けて実行し、結果を要約する
- stack push / sync の前に --dry-run の出力を示す
- 終了コード 8 は未ログイン。auth login を実行せず、私に依頼する
- 終了コード 4 はリベースかマージの衝突。解消方法を提案し、自動で解かない
- 終了コード 6 はMergify APIの失敗。リトライせず内容を報告する
- queue pause と quarantines add は実行しない。必要なら理由案だけ書く

終了コードは、1が分類不能の実行時失敗、2が引数の誤り、3がスタック・ブランチ・コミットが見つからない、4が衝突、5がGitHub API、6がMergify API、7が不正な実行文脈、8が設定や資格情報の不備(未ログインを含む)です。

あわせて、MCPサーバーの認証を端末から操作する場合の考え方はclaude mcp login/logoutの解説と共通する部分があります。ログインはブラウザ承認を人が行い、エージェントには保存済みの資格情報を使わせる分担です。

導入後の確認

導入できたかは、次の順に確かめます。

  1. mergify --help が動く
  2. mergify auth status でアカウントが表示される
  3. mergify queue status --json が応答する
  4. claude plugin list に mergify が出る(JSONでの棚卸しはclaude plugin list --jsonを参照)
  5. 拒否ルールが効いているか、queue pause を依頼して実行されないことを確認する

5番は省かれがちです。拒否したい操作が本当に止まるかは、一度実際に依頼して見ておくと確実です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →