テクノロジー · 実用ガイド
GitHub Actionsのキャッシュが復元されないとき：キー、バージョン、参照範囲、アクセスを比較する
キャッシュが存在しても、現在の実行から読めるとは限りません。削除やランナー変更の前に、作成した実行と復元できなかった実行を比較します。
GitHub Actionsのキャッシュミスだけでは、保存失敗、ランナー故障、キー変更のどれも断定できません。キャッシュのバージョン、ブランチやPRの参照範囲、復元キーの検索順序、アクセスモード、エントリの存続も結果を左右します。
まず、キャッシュを作成した実行と利用できなかった実行の比較記録を作ります。評価済みのキー、パスと圧縮の入力、参照、イベント、リポジトリ、権限、検索結果、保存結果を並べて確認します。
完全一致の失敗、部分復元、PRの範囲制限、削除済みエントリを別々に調べます。キーの変更、キャッシュ削除、権限拡大、ランナー移行より先に証拠を保存します。
作成側と利用側の比較記録を作る
保存に成功した実行と、本来それを再利用するはずだった実行を一つずつ選びます。リポジトリ、ワークフローファイルとコミット、イベント、github.ref、github.ref_name、該当するベース・ヘッド参照、OSとアーキテクチャ、actionのバージョン、評価済み主キー、全復元キー、パス、lookup-only、fail-on-cache-miss、最終ログを記録します。
YAMLの式だけを比較してはいけません。push、pull_request、マトリクス、再利用可能ワークフローで評価値が変わることがあります。ログか安全な診断ステップで実際の値を確認し、トークン、シークレット、認証情報、非公開ファイルの中身は出力しません。
キーとキャッシュバージョンを分ける
キャッシュバージョンはパスや圧縮ツールのメタデータに関係します。同じキーでも、パス入力、プラットフォーム、圧縮環境、actionの実装が違えば互換性のないバージョンになる可能性があります。
式の評価後のパス入力を、順序、ワイルドカード、チルダ、ワークスペース、OSによる違いまで比較し、ランナーイメージとactionのバージョンも残します。タイムスタンプをキーに加えて問題を隠すと新しいエントリが増え、元の比較が難しくなります。
参照範囲を可視性の規則として扱う
pull_request実行が作ったキャッシュはPRのマージ参照に属し、そのPRの再実行から利用できます。ベースブランチや他のPRからは復元できません。現在のブランチや許可されたデフォルトブランチのキャッシュを利用できても、任意の子・兄弟ブランチは対象外です。
両方のイベントと実際の参照を記録します。同じキーがpushでは命中しpull_requestでは失敗するなら、ランナーやパスより先に範囲を比較します。コミュニティの質問は現象の報告であり、原因の証明ではありません。実際の参照をGitHub公式のアクセス規則と照合してください。
cache-hitと復元結果を正しく読む
cache-hitがtrueになるのは主キーが完全一致した場合です。主キーが見つからず復元キーの前方一致でデータを戻した場合、falseでも復元自体は成功しています。falseを常に復元データなしと判断すると余計な処理を招きます。
復元ログ、一致したキー、出力文字列をまとめて保存します。READMEのOutputs欄はミス時を空文字列と説明しているため、true以外をすべてfalseにまとめないでください。ログと合わせて完全一致、部分復元、データ未復元を区別します。部分復元後も依存関係の変更に合わせたインストールが必要な場合があります。 Stack Overflowの質問者は、条件を引用符なしの真偽値ではなく文字列'true'と比較すると解決したと報告しています。これはそのワークフローでの報告であり、すべてのミスの原因を証明するものではありません。
アクセスモードを独立して確認する
ACTIONS_CACHE_MODEの実効値、ワークフローとjobのcache-mode、再利用先に渡る制限、操作を省略したログを残します。readは復元のみ、writeは復元と保存、write-onlyは保存のみ、noneは両方不可です。読み取り禁止で復元を省略した場合もミスとして現れるため、エントリが存在しないとは限りません。
PRを一律に同じ制限と考えないでください。デフォルトブランチの低信頼トリガー制限と、pull_requestのマージ参照による分離は別の規則です。リポジトリ、イベント、参照、実効モードを照合します。ジョブが成功しても保存の拒否や省略があり得ます。警告を保管し、安全な既定値を維持して適切な信頼できる作成側を使います。
エントリが今も存在することを確認する
過去の保存成功は当時の存在しか示しません。容量制限、未使用期間、手動削除、頻繁な入れ替わりによる削除を確認します。権限のあるアカウントでキャッシュ一覧やAPIを使い、キー、参照、作成日時、最終アクセス日時、サイズを調べます。
診断として全キャッシュを削除しないでください。存在しなければ作成ログと一覧結果を保存し、一度だけ管理された再作成を行います。別の参照や非互換バージョンに存在する場合、削除しても可視性の規則は変わらず、証拠だけ失われます。
結果に応じた最小の変更を選ぶ
同じキーのミスなら読み取り許可を確認し、次にバージョンと参照を比較します。部分復元なら後続条件を点検しつつ、必要な依存関係の同期は行います。PRの範囲違いなら信頼できる適切な作成側を使うか分離を受け入れます。不存在なら一度作成して一覧を確認し、不信頼コードのアクセスは広げません。
識別条件が一致し、想定参照からエントリが見える場合は比較記録を添えて調査を依頼します。実行URL、安全な評価値、actionのバージョン、ランナーイメージ、一覧の証拠、最小再現ワークフローがあれば、証拠削除や秘密の開示なしで不具合を調査できます。
