GitHub・プルリク・マージの API・2026年10月24日に確認

GitHub の「Pull Request is not mergeable」と「Head branch was modified」

PUT /repos/持ち主/リポジトリ名/pulls/番号/merge が失敗したときの答えは、GitHub の REST の説明に書いてあります。405 はマージを行えない、409 は sha を送ったがプルリクの先頭がもうそれと合わない、403 はその操作が許されていない、422 は検証に通らないか、窓口を短時間に叩きすぎた、です。前の 2 つの文は、GitHub の以前の API の説明に載っていました：

HTTP/1.1 405 Method Not Allowed

{"message": "Pull Request is not mergeable", "documentation_url": "…"}

HTTP/1.1 409 Conflict

{"message": "Head branch was modified. Review and try the merge again.", "documentation_url": "…"}

和訳：「プルリクはマージできません」と「元のブランチが変更されました。見直してからもう一度マージしてください」。

405「Pull Request is not mergeable」

文には理由が書いてありません。GitHub の説明と公開の報告から、次の場合があります：

GitHub がまだ確かめ終わっていない。GitHub の説明では、プルリクが作られたり変わったりすると、GitHub はマージできるかを裏の処理で確かめ、終わるまで mergeable は null です。公開の報告では、push やブランチの更新の直後に送ったマージに、REST でも GraphQL でも同じ文が返り、数秒後には同じプルリクがマージできる状態になっていました。
対象のブランチと競合している。mergeable が false です。
ブランチのルールをまだ満たしていない。ブランチの保護のルールかルールセットが、マージの前に承認のレビュー・通ったステータスチェック・対象のブランチに追いついたブランチを求めています。
下書きである。下書きは、レビューの準備完了にするまでマージできません。

公開の報告には、405 で Base branch was modified. Review and try the merge again.（和訳：対象のブランチが変更されました。見直してからもう一度マージしてください）が返った例もあります。プルリクを読み直してからマージします。

いまどうなっているか

curl -H "Authorization: Bearer your-token" https://api.github.com/repos/OWNER/REPO/pulls/42

mergeable は true・false・null（まだ確かめている途中：少し後にもう一度読む）で、mergeable_state は状態をひと言で表します（たとえば unknown）。状態の意味は GraphQL の説明にあります。mergeable は MERGEABLE・CONFLICTING・UNKNOWN のどれかで、mergeStateStatus は次のどれかです：

CLEAN：マージでき、コミットのステータスも通っている。UNSTABLE：マージできるが、ステータスが通っていない。HAS_HOOKS：マージでき、ステータスが通り、pre-receive フックがある。
BLOCKED：マージが止められている。BEHIND：元のブランチが古い。
DIRTY：マージのコミットをきれいに作れない。UNKNOWN：まだ状態を決められない。

409「Head branch was modified. Review and try the merge again.」

レビューした先頭を sha で送ったが、ブランチの先頭が別のコミットになっています。公開の報告では、プルリクを読んでからマージするまでの間に、コミットが push されていました。対象のブランチを取り込むスクリプト自身の手順や、依存関係を更新するボットによってです。古い sha のまま送り直しても、同じように断られます。プルリクを読み直して新しいコミットを見てから、新しい先頭でマージします。

非同期のマージの API

GitHub の説明は、いまは代わりに PUT …/pulls/番号/merge-async を勧めています。上の窓口は、積み重ねたプルリク（stacked）とマージキューに対応していません。こちらは、受け付けると 202 と結果を取りに行くための ID を返し、もうマージ済みかマージキューに入っていればすぐ 200、マージできない（閉じている・下書き）ならすぐ 400、同じプルリクの非同期のマージがもう待っていれば 409 を返します。最初の段階では、ブランチの保護のルールとルールセットは確かめません。

直し方

push の直後の 405：数秒待ち、mergeable が null でなくなるまで読み直してから、もう一度マージする。
競合での 405：ブランチを更新するか、手元のクローンで競合を解決して push する。
ブランチのルールでの 405：ルールが求めるレビューや通ったチェックをそろえる、遅れていればブランチを更新する、または自動マージを入れて、ルールを満たしたときに GitHub にマージさせる。
409：新しいコミットをレビューしてから、新しい先頭の sha でマージする。
403：トークンかそのアカウントに、ここでマージする権限がありません。「Resource not accessible by personal access token」へ。

IntelliJ IDEA ではボタンが押せないまま、断られたマージは何も出ない

IntelliJ IDEA に入っている GitHub の機能がプルリクをどうマージするか。ソース（2026年10月30日に確認・IntelliJ IDEA：GHPRReviewFlowViewModelImpl.kt・GHPRMergeabilityStateBuilder.kt・GHPullRequestMergeStateStatus.kt・GHPRDetailsServiceImpl.kt・GithubApiRequests.kt）では：

Merge… と Squash and Merge… が押せるのは、GitHub のマージの状態が CLEAN・HAS_HOOKS・UNSTABLE のときだけです（マージ先にブランチ保護のルールがあれば、管理者は BEHIND・BLOCKED でも）。UNKNOWN・DIRTY・DRAFT の間は押せません。Rebase は GitHub がそのプルリクを rebase できると言うときだけです。どれも、リポジトリでその方法が許されていること、書き込みの権限、マージ先にブランチ保護のルールがあればそこへ push できることも要ります。
マージは上の REST の API（PUT /repos/OWNER/REPO/pulls/NUMBER/merge）で、非同期の方ではありません。最後に読んだ元のコミットを sha として送るので、その後に push されたコミットがあると上の 409 になります。Merge… と Squash and Merge… は先にコミットの文を聞きます。
GitHub がマージを断ると、405 でも 409 でもそれ以外でも、画面には何も出ません。ソースはエラーを IDE のログに書くだけで、画面に出すのはまだ先の作業と記されています。その後プルリクを読み直すので、ボタンは新しい状態に合わせて変わります。理由は上の curl でプルリクを読んで見ます。

IntelliJ IDEA で GitHub のプルリクを見るなら

Lesstep の Pull Request Inbox for GitHub は、JetBrains IDE（2024.1 以降）のプラグインです。マージの前に、プルリクのマージの条件を、マージを止めているものから順に見せます。承認・変更の依頼・チェック・競合・対象のブランチのルールをまだ満たしていないこと・ルールが求める対象のブランチの新しいコミット・下書きか・あなたのアカウントがマージできるか、です。GitHub がまだ確かめている間は、そう言います。マージするのは、画面に出ていた先頭のコミットです。GitHub が断ったときは、そう言います。405 なら今はマージできないと GitHub の文を添えてマージの条件を見るように、409 ならブランチが変わったので読み直すように、と。自動マージを入れることと、ブランチの更新もできます。受信箱・差分・会話は無料、承認・コメント・マージは Pro（月 US$1.50・30日間の無料試用つき）です。画面は日本語です。

GitHub は GitHub, Inc. の商標、IntelliJ IDEA は JetBrains s.r.o. の商標です。このページは GitHub, Inc.・JetBrains のいずれとも提携しておらず、承認も受けていません。