CI が全部 green なのに auto-merge されない PR を、原因から特定して自動マージに乗せる

GitHub の auto-merge を仕込んだのに、PR が CI 全 pass・MERGEABLE のまま何日も止まる。 このとき真っ先に疑うのは権限だが、**多くの場合の原因は「その PR が fork から出ていること」**で、 権限を直しても永久に解決しない。原因の切り分けから恒久対策までを、実行できるコマンドで示す。

前提

• gh CLI がインストール済みで、対象リポジトリにアクセスできるアカウントで認証済み
• 対象リポジトリに auto-merge を有効化する GitHub Actions ワークフローが存在する
• 以下では <OWNER>/<REPO> を対象リポジトリ、<PR番号> を止まっている PR の番号とする

ステップ1: 症状を数値で確定する

gh pr view <PR番号> --repo <OWNER>/<REPO> \
  --json state,mergeable,autoMergeRequest,headRepositoryOwner \
  --jq '{state, mergeable, autoMerge:(.autoMergeRequest!=null), headOwner:.headRepositoryOwner.login}'

• autoMerge が false なら auto-merge がそもそも有効化されていない。CI の緑とは無関係。
• headOwner が対象リポジトリの owner と違えば、その PR は fork から出ている。

ここで mergeable: "MERGEABLE" かつ autoMerge: false が出たら、CI をいくら待っても状況は変わらない。

ステップ2: 権限を実測する（記憶や過去メモを根拠にしない）

gh api repos/<OWNER>/<REPO> --jq .permissions
gh api repos/<OWNER>/<REPO>/collaborators/<自分のログイン名>/permission --jq .permission

権限は途中で付与・剥奪される。過去の記録に「push できない」と書いてあっても、着手時に1回叩いて確かめる。 push: true なら、fork を使う理由はもう無い。

ステップ3: ワークフローの除外条件を読む

auto-merge を有効化するワークフローの本体を読む。ネットワーク越しでよい。

gh api repos/<OWNER>/<REPO>/contents/.github/workflows/<ワークフロー名>.yml --jq .content | base64 -d

典型的な実装は、次のような条件をすべて満たす PR だけを対象にしている。

1. head.repo.full_name が base リポジトリと同じ（fork からの PR は対象外）
2. draft ではない
3. PR の author が collaborator である
4. 特定のラベル（例: automerge）が付いている
5. 変更ファイルが保護対象パターン（.github/workflows/*、資格情報・環境変数系のファイル名）に当たらない

条件1は、fork の GITHUB_TOKEN と第三者のコードに書き込み権限を渡さないための意図的な設計であることが多い。 ここを緩めると、誰でも PR を投げれば信頼されたトークンでワークフローを動かせる状態に近づく。 緩めるべきではない。 権限があるなら fork をやめる方が正しい。

ステップ4: 正しい経路で出し直す

# 1. base リポジトリに直接ブランチを push する（fork ではない）
git push origin HEAD:refs/heads/<ブランチ名>

# 2. PR を作る
gh pr create --repo <OWNER>/<REPO> --base main --head <ブランチ名> \
  --title "<タイトル>" --body-file -

# 3. ラベルを付ける（これがワークフローの起動条件）
gh pr edit <PR番号> --repo <OWNER>/<REPO> --add-label <ラベル名>

# 4. 有効化されたことを必ず確認する
gh pr view <PR番号> --repo <OWNER>/<REPO> --json autoMergeRequest \
  --jq '{autoMerge:(.autoMergeRequest!=null), enabledBy:.autoMergeRequest.enabledBy.login}'

4 で autoMerge: true になり、enabledBy がワークフローを動かした bot（例: app/github-actions）に なっていれば成功。あとは残りのチェックが終わり次第、人の操作なしでマージされる。

最大の落とし穴: ラベル忘れは「成功」に見える

ワークフローは対象外の PR に対しても ジョブ自体は成功で終わる（条件に合わないので何もせず exit 0）。 そのため PR 画面では全チェックが緑になり、自動マージされるように見えて永久に止まる。

緑を見て安心せず、必ず autoMergeRequest が null でないことを確認する。 これを確認手順に入れない限り、同じ滞留が繰り返される。

補足: マージ API は2系統ある

手動でマージするとき、gh pr merge は GraphQL の mergePullRequest を呼ぶ。 権限があってもこちらだけが拒否されることがある。その場合は REST を試す。

gh api -X PUT repos/<OWNER>/<REPO>/pulls/<PR番号>/merge -f merge_method=squash

片方のエラーだけを見て「マージできない」と結論しない。

恒久対策として残すこと

• リポジトリの docs に「PR は fork ではなく base リポジトリのブランチから出す」と手順を書く
• ラベル付与と autoMergeRequest の確認を、PR 作成手順の一部として明記する
• 保護対象パターン（ワークフロー・資格情報）に触る変更は、引き続き人のレビューとマージを必須にする。 ここは自動化の対象外だと明示的に書いておくと、後から誰かが「不便だから」と緩めにくくなる

検証できたこと（実測）

同一内容の変更を2つの経路で出して比較した結果が次のとおり。

• fork から提出: CI 全 pass・MERGEABLE のまま 2日滞留し、最終的に人がブラウザでマージした
• base リポジトリのブランチ + ラベル: 提出から 約8分で bot が auto-merge を有効化し、人の操作ゼロでマージ完了