GitHub Actions cache-mode: 緑色のCIの裏に潜むキャッシュ権限を確認する
CIが緑色（成功）で終わったのに次の実行で依存関係が再ダウンロードされる場合、キャッシュキーから修正してしまいがちです。今後は、権限が原因で保存がスキップされていないかも確認する必要があります。成功したワークフローであるという事実だけでは、キャッシュが作成されたとは判断できないためです。
GitHubは2026年9月10日にcache-modeの一般提供（GA）を発表しました。github.comのすべてのプランにおいて、ワークフローまたはジョブ単位でキャッシュアクセスを設定できます。従来の読み取り専用デフォルトについて扱った前回の記事から一歩進め、今回は明示的な設定と検証方法に焦点を当てます。
確認された機能: 復元と保存の4つの組み合わせ
readは復元のみ、writeは復元と保存を許可します。write-onlyは保存のみを許可し、noneは両方を禁止します。writeという名前を保存専用と誤解しないことが最初のチェックポイントです。
ジョブで宣言された値は、ワークフロー全体の設定よりも優先されます。一方で、再利用可能ワークフローの呼び出しでは、呼び出し元が許可したレベルを超えるアクセス権限を受け取ることはできません。1つのファイルの宣言だけを読んで、実行全体の実際の権限を判断しないようにしてください。
緑色の実行結果も保存の証明にはならない
公式ドキュメントでは、許可されていないキャッシュ操作は情報ログを残してそのまま続行されると説明されています。ブロックされた復元はキャッシュミスとして処理され、ブロックされた保存は実行されません。ワークフロー自体は失敗しないという点が、オブザーバビリティ上の重要なポイントです。
したがって、運用記録を実行の成否とキャッシュ結果に分けておくことが有用です。どのイベントがトリガーしたか、どのモードが適用されたか、復元が行われたか、保存がスキップされたかを1回の実行ログから確認します。これは公式の機能説明に基づいて提案する運用手法であり、自動的に提供される新しいダッシュボード機能ではありません。
適用前に小さな権限表を作成する
リポジトリの実際のワークフローを開き、キャッシュを生成するジョブと消費するジョブを特定してください。信頼できるブランチで依存関係を準備するジョブ、外部からの変更をテストするジョブ、デプロイ成果物を検証するジョブをすべて同一の権限でまとめる必要はありません。
各ジョブについて2つの問いを書き出します。「このジョブは既存のキャッシュを読み取る必要があるか」「このジョブの結果を次回の実行が読み取れるよう残してもよいか」。両方とも不要であれば、惰性でキャッシュを適用していないか見直すことができます。ただし、実際の設定はリポジトリの信頼境界とビルド構造に合わせて決定する必要があります。
最小限の実験: 読み取り専用の消費ジョブ
たとえばテスト用ワークフローの最上位でcache-mode: readを明示し、ジョブごとの上書きがないことを確認します。キャッシュを使用した場合のテスト結果と、キャッシュがない状態のテスト結果が一致するかを比較します。キャッシュは実行時間を短縮するための補助手段であるべきなので、キャッシュの有無によって正確性が変わるようであれば、まずビルド時の前提条件を点検する必要があります。
この実験の合格基準は、CIが成功したという1行だけではありません。復元の試みと保存のスキップを説明でき、次の実行でも同じ入力で再検証できる必要があります。実験前後のコミット、トリガー、有効な設定、ログの場所を併せて残しておけば、他の同僚も判断を再現しやすくなります。
再利用可能ワークフローは呼び出し経路まで追跡する
共通ワークフローに安全なデフォルト値を設定していたとしても、呼び出し側と個別のジョブ設定を併せてレビューする必要があります。リポジトリ間で同じファイルを呼び出しているという事実と、同一の権限で実行されているという事実は同義ではありません。
レビューの際は、呼び出し元から始めてジョブのキャッシュ宣言、呼び出されたワークフローの順にトレースしてみてください。想定していた権限と実際のログが異なる場合は、キーをむやみに複雑にする前に設定の出所を特定します。これは再利用を多用する組織において診断時間を短縮するための提案であり、測定された性能改善の数値を意味するものではありません。
注意すべき例外と適用の順序
pull_request_targetのような信頼度の低いイベントに対してwriteまたはwrite-onlyを明示すると、読み取り専用のデフォルト制限を上書きしてしまい、キャッシュ汚染のリスクが高まります。GitHubはこの場合、警告のアノテーションを追加します。警告を消すために安易に書き込み権限を増やすような対応は避けるべきです。
反対に、すべてのキャッシュを無効にする選択にもコストが伴います。ダウンロードやビルドの時間が増加する可能性があるため、代表的なジョブ1つで実行時間を直接比較したうえで適用範囲を広げてください。数値を推測してパフォーマンス向上を約束するのではなく、セキュリティ上必要な制限と許容できる遅延をチーム全体で決めるほうが賢明です。
チームが今すぐ確認すべき問い
今日取り組むべきことは、新しい設定を全リポジトリに一括適用することではありません。重要なワークフローを1つ選び、キャッシュの生成者と消費者を特定して権限を書き出し、1回の実行ログで復元と保存の根拠を確認することです。デプロイジョブであれば、担当者がログを読み、想定通りに動作しているかを検証できるよう、変更は小さく保ちましょう。
実務で生じやすい疑問は、「保存ステップがスキップされたのになぜCIは成功したのか」という点です。本記事ではそのような混乱を公式の挙動に基づいて解説したものであり、独自のコミュニティアンケートや一般的な障害発生率を主張するものではありません。新機能を導入する際にパフォーマンス結果と権限結果をそれぞれ確認するようにすれば、次回以降のキャッシュトラブルをより正確に切り分けることができます。