# CI が全部 green なのに auto-merge されない PR を、原因から特定して自動マージに乗せる GitHub の auto-merge を仕込んだのに、PR が CI 全 pass・MERGEABLE のまま何日も止まる。このとき真っ先に疑うのは権限だが、**多くの場合の原因は「その PR が fork から出ていること」**で、権限を直しても永久に解決しない。原因の切り分けから恒久対策までを、実行できるコマンドで示す。 ## 前提 - `gh` CLI がインストール済みで、対象リポジトリにアクセスできるアカウントで認証済み - 対象リポジトリに auto-merge を有効化する GitHub Actions ワークフローが存在する - 以下では `/` を対象リポジトリ、`` を止まっている PR の番号とする ## ステップ1: 症状を数値で確定する ```bash gh pr view --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: 権限を実測する（記憶や過去メモを根拠にしない） ```bash gh api repos// --jq .permissions gh api repos///collaborators/<自分のログイン名>/permission --jq .permission ``` 権限は途中で付与・剥奪される。過去の記録に「push できない」と書いてあっても、着手時に1回叩いて確かめる。 `push: true` なら、fork を使う理由はもう無い。 ## ステップ3: ワークフローの除外条件を読む auto-merge を有効化するワークフローの本体を読む。ネットワーク越しでよい。 ```bash gh api repos///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: 正しい経路で出し直す ```bash # 1. base リポジトリに直接ブランチを push する（fork ではない） git push origin HEAD:refs/heads/<ブランチ名> # 2. PR を作る gh pr create --repo / --base main --head <ブランチ名> \ --title "<タイトル>" --body-file - # 3. ラベルを付ける（これがワークフローの起動条件） gh pr edit --repo / --add-label <ラベル名> # 4. 有効化されたことを必ず確認する gh pr view --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 を試す。 ```bash gh api -X PUT repos///pulls//merge -f merge_method=squash ``` 片方のエラーだけを見て「マージできない」と結論しない。 ## 恒久対策として残すこと - リポジトリの docs に「PR は fork ではなく base リポジトリのブランチから出す」と手順を書く - ラベル付与と `autoMergeRequest` の確認を、PR 作成手順の一部として明記する - 保護対象パターン（ワークフロー・資格情報）に触る変更は、引き続き人のレビューとマージを必須にする。ここは自動化の対象外だと明示的に書いておくと、後から誰かが「不便だから」と緩めにくくなる ## 検証できたこと（実測）同一内容の変更を2つの経路で出して比較した結果が次のとおり。 - fork から提出: CI 全 pass・MERGEABLE のまま **2日滞留**し、最終的に人がブラウザでマージした - base リポジトリのブランチ + ラベル: 提出から **約8分**で bot が auto-merge を有効化し、人の操作ゼロでマージ完了 ---