GitHub Actionsの必須チェックがPendingのままなら、「実行中なので待てばよい」と決めず、対象のcheckが作られているかを確認します。workflow自体がfilterで起動していない場合、待っても報告されません。最新commit、起動event、check名、報告元を揃え、どの層で止まっているかを分けます。
この記事はPRの必須ステータスチェックの診断を扱います。repository設定、branch protection、ruleset、workflowの変更・起動、commitやmergeは実施していません。状態例は架空で、特定PRを解除・公開した報告ではありません。
目次
merge欄とActions一覧を同じSHAで見る
PRのmerge欄で待っているcheck名を控え、head commit SHAと、表示されているtest merge commitのどちらが評価対象かを確認します。以前のcommitで緑だったことは、現在の条件を満たした証拠にはなりません。Actions一覧の同名workflowが成功していても、対象SHAとeventが違えば別の結果です。
GitHubの公式トラブルシューティング（新しいタブで開く）は、最新SHAのcheckが必要で、test merge commitにステータスがある場合はそちらを確認するよう説明しています。表示名だけで同じ検証と判断しないことが出発点です。
表は横にスクロールできます
| 観測 | 次の調査 | 待つだけでよいか |
|---|---|---|
| 対象runが実行中 | job log・runner・依存 | 進捗と原因次第 |
| 対象runが存在しない | on/filter/event | 新規報告がない理由を確認 |
| run成功、必須checkは未報告 | SHA・check名・報告元 | 別結果の可能性 |
| jobがSkipped | 条件と依存job | workflow skipと分ける |
| 古いcommitだけ成功 | 最新commitの起動条件 | 旧成功では満たさない |
workflow全体のskipと、job条件のskipを分ける
公式資料は、path filter、branch filter、commit messageでworkflowがskipされると、関連するrequired checkがPendingに残り得ると説明しています。一方、jobの条件によるskipは同じ扱いではありません。Actionsのrunがないのか、run内のjobがSkippedなのかを先に区別します。
架空例として、scripts/**が変わった場合だけ動くworkflowのbuildを必須にすると、READMEだけのPRではそのworkflowが起動せず、結果が報告されない場合があります。空commitを繰り返す前に、実際の変更pathとfilterを照合します。skip用のcommit messageを使っていないかも確認します。
修正の方向は、必要な検証結果をどの変更でも報告できる設計にすることです。高価なtestだけ条件化し、必須の集約jobで必要な結果を評価する方法などを検討します。ただし集約jobを常に成功にするだけでは、実際に失敗したtestまで通してしまいます。
needsがあるjobは、前段失敗時の評価を確認する
後続jobが前段の失敗で実行されない場合、単に「成功したjobが一つある」では全体を判定できません。公式資料には、needsを持つrequired checkでalways()を使う案内がありますが、always()は結果を自動判定する関数ではありません。
集約jobは、必要なjobの成功・失敗・cancelled・許容したskipを読み、要件に従って自分の結論を出す必要があります。skipを許す条件と、実行されなかったら失敗にする条件を決めます。これはworkflow設計の方針であり、そのまま導入すれば検証が正しいと保証する完成コードではありません。
表は横にスクロールできます
| 前段の状態 | 集約時の確認 | 避ける扱い |
|---|---|---|
| success | 必要な検査が実行されたか | 名前だけで全検証済み |
| failure | 失敗を反映するか | 集約jobだけ無条件success |
| cancelled | 最新runで置き換わる設計か | 古い成功を流用 |
| skipped | 意図した条件で不要か | 理由なしにすべて許容 |
実際のcheck名と期待する名前を照合する
rulesetの公式診断資料（新しいタブで開く）は、workflow jobとreusable workflowでcheck名の形式が異なることを説明しています。workflowのファイル名だけを必須check名として探さず、実際に報告された名前と比較します。
jobをrenameした後も旧名をrequireしていないか、別workflowに同名jobがないか、reusable workflowへの移行で名前が変わっていないかを確認します。同じ名前のcheckとコミットステータスの両方がある場合も、片方の成功だけで満たすとは限りません。expected sourceとしてGitHub Appを指定しているなら、報告したAppも照合します。
設定を変える場合は、対象branchやruleset、元の必須名とsource、変更理由を記録します。診断を省略するために必須条件を削除したり、管理者bypassでmergeしたりすることを標準の復旧にしません。
起動eventとmerge queueの検証経路を見る
workflow_dispatchで手動成功したrunがあっても、そのcheckがPRのruleset評価を満たすとは限りません。公式資料は、PRで評価されるworkflow jobのeventに条件があり、merge queueには別のmerge_groupが必要と説明しています。利用しているqueueの有無と、待たれているSHA・eventを確認します。
fork権限の問題を直すためだけにpull_request_targetへ置換しないようにします。eventを変えると、どのコードがどの権限で動くかも変わります。必要な検証経路と信頼境界を保った形で、対象eventの公式仕様に合わせます。
必須条件を満たした根拠で閉じる
許可された検証では、code変更、対象外pathだけの変更、前段失敗、cancelled、意図したskip、merge queueを使う場合の経路を確認します。YAMLが読めたことや手動runが成功したことだけを、PRのrequired check成功と同一にしません。
復旧記録には、対象PR/SHA、未報告だったcheck、原因となったfilter・名前・event・source、採用した最小差分、実際に確認した結果を残します。変更後もPendingなら、最新のrunとmerge欄を同じSHAで見直し、別の未報告項目を前回の原因へ無理に当てはめないようにします。