PR番号ではなく、
Exact SHAを信じる

AIエージェントへ実装を任せると、報告は自然言語で返ってきます。「CIはGREENです」「レビュー済みです」「mainへ入っています」。どれも文章としては正しく読めます。

一方でGitHubの側には、PR head、CIが実際に検査したcommit、レビューが読んだ差分、Ownerが承認したcommit、merge後にmainへ生成されたcommit、デプロイが使ったcommit、本番がいま配信しているcommitという、別々のcommitになりうる7つの状態が並んでいます。

会話の中では1つに見えるものが、システムの中では7つあります。ここがずれたまま操作すると、検証済みのコードと操作対象が別物になります。

結論を先に書きます。

AIエージェント運用では、PR番号ではなく40桁のcommit SHAを操作対象の識別子として扱います。

PR番号は可変参照です。同じ番号のまま中身が入れ替わります。SHAは内容へ固定された識別子です。検証、承認、merge、デプロイ、本番確認は、すべて同じSHAを指しているかどうかで結び付けます。

Incident Card

INCIDENT:
remote branchには新しいcommitが載っていたのに、GitHubのPull Request APIが古いheadを返し続け、Controllerがその古いheadをmergeした

SYMPTOM:
検証済みの修正3件（既知High 2件を含む）を取りこぼした状態がmainへ入った

FALSE_ASSUMPTION:
PR番号とCIのGREEN表示が一致していれば、merge対象は検証済みのコードと同じである

ROOT_CAUSE:
検証したSHAと操作するSHAを別々に取得して突き合わせる工程が無く、単一のPR head表示を信じていた

IMMEDIATE_FIX:
merge直前にremote branch refを別経路で取り直し、PR APIのheadと一致しなければmergeしない

SYSTEM_FIX:
PR_HEAD_SHAからPRODUCTION_SHAまで7つのSHAへ別々の名前を与え、等式が崩れたらUNKNOWNをDENYとして扱う

REMAINING_RISK:
squash merge後のSHAはPR headと別物であり、PR側のexact-head CIをそのまま流用できない

PR番号は、中身が入れ替わる可変参照である

Pull Requestの番号は作業の入れ物です。中身であるcommitは、push、rebase、force push、base branchの前進によって変わります。番号は変わりません。

そのため次の文はいずれも、単独では検証対象を特定できません。

• 「PR #1234はCIがGREENです」
• 「PR #1234はレビュー済みです」
• 「PR #1234をmergeしました」

どれも「いつの#1234か」を含んでいません。AIエージェントが複数走り、mainが数十分単位で進む環境では、この欠落が判断を壊します。

2026-08-17、Netsujoのリポジトリで実際に次が起きました。remote branchには3つのcommitがpush済みだったのに、GitHubのPull Request APIが古いheadを返し続けました。Controllerはその古いheadをmergeし、検証済みの修正3件を取りこぼした状態がmainへ入りました。

このときmerge APIのsha preconditionは役に立ちませんでした。preconditionが比較するのはGitHub自身が持つPR headであって、remote branchの実refではありません。PR headが古ければ、古い値どうしで一致します。

誤った前提：CIがGREENなら、merge対象は検証済みである

「CIがGREEN」という表示は、何かのcommitに対して検査が通ったことしか示しません。示していないのは次です。

• どのcommitを対象に走ったのか
• そのcommitがいまのPR headと同じか
• required checkだったのか、任意のjobだったのか
• 変更内容によってskipされた検査は無かったか
• run完了後にPR headが進んでいないか

同じ問題は再実行にも出ます。GitHub Actionsのmanual rerunは、元のrunの古いevent payloadを再利用します。したがってrerunのGREENは、rerunした時刻ではなく元のevent時点のSHAに対する結果です。

Netsujoのリポジトリでは、この穴を検査で塞いでいます。.github/workflows/ci.ymlの先頭にはReject stale PR head rerunというstepがあり、eventのhead SHAとlive branch refをGit protocolで照合し、一致しなければSTALE_PR_HEAD=FAILで落とします。.github/workflows/pr-exact-head-ci.ymlは、local checkout、event head、remote branch refの3経路を突き合わせ、1つでも欠けたり食い違ったりすればFAILにします。

根本原因：同一性の確認が、どこにも実装されていなかった

事故の原因は、AIの判断力でも報告の言葉遣いでもありません。検証したSHAと操作するSHAを機械的に突き合わせる工程が、経路上に存在しなかったことです。

人間の運用でも同じ構造は起きます。ただしAIエージェントを複数並列で走らせると、mainが動く頻度と報告の量が増え、目視での照合が追いつかなくなります。

その場の対処：merge直前に、独立した経路でheadを取り直す

最初に入れた対処は単純です。merge直前に、GitHubのPR APIとは別のAPIからremote branch refを取り直し、突き合わせます。

scripts/agent-os/integration-controller.mjsのevaluateHeadIdentityが、この判定の正本です。

PR_API_HEAD_SHA = REMOTE_BRANCH_REF_SHA = REQUIRED_CI_TARGET_SHA = MERGE_EXPECTED_HEAD_SHA

この等式が成立しない場合の返り値は、すべてDENY側です。

重要なのは、取得できなかった場合もDENYにしていることです。UNKNOWNをALLOWへ倒すと、判定の欠落が自動承認へ化けます。

仕組みへの変換：7つのSHAへ、別々の名前を与える

同一性を確認するには、まず同一視をやめる必要があります。Netsujoでは次の7つを別々の変数として扱います。

この分離は、リポジトリ上で次のように実装されています。

• OWNER_AUTHORIZED_SHAは、PR本文へ残す認可行で表現します。対象のPR番号と40桁のcommit SHAを組で束縛する形式です。PR番号が違えばDIFFERENT_PR_AUTHORIZATION、SHAが違えばAUTHORIZATION_SHA_MISMATCHになります。承認は「このPR」ではなく「このPRのこのcommit」に対して与えます。
• MERGED_SHAは、PR headとは別物です。squash mergeが作るcommitはPR headそのものではありませんし、その間にmainが動いていれば内容も変わります。そこで.github/workflows/candidate-exact-sha-gate.ymlが、merge後の候補SHAをcheckoutしてlint、typecheck、test、buildを回し直し、そのSHAへcommit statusを書きます。
• PRODUCTION_SHAは、scripts/deploy-policy/resolve-production-sha.mjsが本番aliasからdeploymentを辿って確定します。期待値は人の入力ではなくworkflowの実行対象commitを正本にしており、取得失敗、記録が空、食い違いはすべて失敗になります。

検証権限と記録権限を分ける

candidate-exact-sha-gate.ymlでは、候補コードを実行するjobにstatuses: writeを与えていません。statusを書くjobは候補コードを1行も実行しません。検証対象のコードとその依存は任意のコマンドを実行できるため、そこへ書き込み権限を置くと、判定結果そのものを偽造できてしまいます。

同一性の設計は、値の照合だけでは終わりません。その値を誰が書けるかまで含めて初めて成立します。

再利用できるExact SHA照合チェックリスト

自組織へ移すときは、次を順に確認します。

1. 報告文へPR番号だけでなく40桁SHAを必須項目として入れているか
2. PR headを2経路（PR APIとremote branch ref）から独立に取得しているか
3. CI runが対象としたSHAを記録し、いまのPR headと突き合わせているか
4. 再実行のGREENが、元eventの古いSHAに対する結果でないことを検査しているか
5. 承認をPR単位ではなくSHA単位で記録しているか
6. merge後SHAに対して、PR側のCIとは別に検証を回しているか
7. デプロイ対象SHAと本番が配信中のSHAを突き合わせているか
8. いずれかが取得できない場合をDENYにしているか

短縮SHAは避けます。判定はすべて40桁小文字で行い、形式が違う時点で落とします。

Evidence

適用限界

• ここで扱うのは、GitHubとGitHub Actionsを使う運用です。他のホスティングでは、同等の情報をどこから2経路で取れるかを個別に設計する必要があります。
• 全12回の事故録のうち、本記事はmerge前後の同一性までを扱います。デプロイ後の本番確認そのものは別の回で扱います。
• 7つのSHAをすべて機械で突き合わせる構成は、AIエージェントが並列でmergeを行う環境を前提にした当社の運用目安であり、変更頻度の低い小規模開発へそのまま持ち込むと管理コストが価値を上回る場合があります。

残るリスク

• squash mergeが作るcommitはPR headと別物なので、PR側のexact-head CIをそのまま流用できません。merge後SHAには専用のgateが要ります。
• commit statusがsuccessでも、それがどのworkflow runから書かれたかを確認しなければPASSとして扱えません。statusを書ける主体を限定する統制が別に必要です。
• workflow_dispatchは選択したrefにある定義で実行されます。定義そのものを書き換えられる主体に対しては、workflow内のguardは防御になりません。
• SHAを揃えても、検査の中身が薄ければ「検証済み」の意味は薄いままです。同一性は前提であって、品質そのものではありません。

まとめ

AIエージェントの報告は自然言語で届き、システムの状態は40桁の識別子で決まります。この2つを結び付ける鍵がExact SHAです。

PR番号     … 作業の入れ物。中身は入れ替わる
Exact SHA … 内容へ固定された識別子。検証と操作を結ぶ唯一の鍵

PR番号で会話し、SHAで判断します。取得できない値はUNKNOWNとして扱い、UNKNOWNはALLOWにしません。

よくある質問

PR番号を使うこと自体が問題なのですか

問題ではありません。PR番号は人が作業を指すための便利な参照です。避けるべきは、PR番号だけを根拠に検証済みかどうかを判断することです。会話はPR番号、判定は40桁SHAと役割を分けます。

CIがGREENなら、そのままmergeしてよいのではありませんか

GREENはあるcommitに対する結果です。そのcommitがいまのPR headと同じか、required checkだったか、変更内容でskipされた検査が無かったかまでを確認して初めて、merge対象の検証済みを主張できます。

squash mergeのあとに、もう一度CIを回す必要はありますか

PR headとmerge後SHAは別物なので、PR側の結果をそのまま流用できません。Netsujoではmerge後の候補SHAをcheckoutしてlint、typecheck、test、buildを回し直し、そのSHAへstatusを残しています。

短縮SHAで運用してもよいですか

推奨しません。当社の運用では、判定に使う値をすべて40桁小文字に固定し、形式が違う時点で失敗させています。短縮形は人が読むための表示に限定します。

AIが「SHAは一致しています」と報告した場合、それを信じてよいですか

自己申告は証拠ではありません。値を取得した経路、対象のrun、判定コードが記録に残っているかを確認します。判定を行う側と、その結果を書き込む側の権限を分けておくことも同時に必要です。