GitHub Actions(GitHubが提供するCI/CDの実行基盤)でビルドを高速化するためにactions/cacheを使っているものの、ときどきキャッシュが効かず「なぜか今日だけ遅い」という経験がある方に向けた内容です。クラウド上のCI環境ではディスクが毎回使い捨てになるため、依存関係のキャッシュはビルド時間とコストを左右する重要な要素です。原因が分からないまま再実行で凌いでいる現場の参考になれば幸いです。
GitHub Actionsのキャッシュは、共有ファイルシステムでもネットワークマウントでもありません。実体は「キー文字列に紐づいた不変のアーカイブ(書き換え不可の圧縮ファイル)」です。ジョブの終了時にディレクトリを固めて保存し、次のジョブが同じキーを指定したときだけ復元されます。1文字でもキーが違えば、復元は失敗(キャッシュミス)として扱われます。
ここで重要なのは、キャッシュミスはエラーとして報告されない点です。ステップはログを1行出して終了コード0(正常終了)を返し、そのまま後続のインストール処理に進みます。CIのログをざっと眺めるだけでは、キャッシュが効いていないことに気づけません。
キー解決の仕組みを段階的に見る
actions/cacheの設定にはkey(完全一致させたい文字列)と、任意でrestore-keys(前方一致で探す候補リスト)を指定します。まずkeyに完全一致するアーカイブを探しにいきます。
一致すれば復元が行われ、cache-hitという出力変数がtrueになります。このときジョブ終了時の保存処理はスキップされます。すでに同じキーのアーカイブが存在するため、書き込む必要がないからです。
完全一致がなければ、restore-keysに書かれた文字列を前方一致のプレフィックスとして順番に探します。最も新しい該当エントリを「部分復元」として復元しますが、cache-hitはfalseのままです。ジョブ終了時には、現在のkeyで新しいアーカイブが改めて保存されます。
- uses: actions/cache@v6
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-
# 部分復元はロックファイルの内容と一致する保証がないため、必ず npm ci で整合性を取る
- run: npm ciここで使われているhashFilesは、指定したファイルの中身からハッシュ値(内容を要約した固定長の文字列)を計算する関数です。依存関係ファイルが変わるとハッシュ値も変わり、自動的に新しいキーになります。ブランチ名のような固定値だけでキーを作ると、依存関係が更新されてもキャッシュが更新されず、古い内容の上に新しいコードを積み続けることになります。
3つの上限がヒットを決める
キャッシュが見つからない原因の多くは、公式ドキュメントに明記された3つの上限のどれかに該当します。どれも通知なしに静かに発生するのが厄介な点です。
| 上限の種類 | 仕様 | 現場で起きる現象 |
|---|---|---|
| 総容量 | リポジトリごとに既定10GB(Enterprise・組織・リポジトリ管理者は引き上げ可能) | LRU(最も使われていないものから)方式で削除され、巨大なビルドキャッシュが他の依存関係キャッシュを押し出す |
| 保持期間 | 7日間アクセスがないエントリは自動削除 | 週末に動きが止まるリポジトリは月曜に必ずキャッシュが冷えた状態に戻る |
| スコープ | 実行中のブランチと既定ブランチのキャッシュのみ復元可能。プルリクエストはベースブランチも読める | 新規の機能ブランチは既定ブランチが先にキャッシュを作っていない限り毎回コールドスタートになる |
キャッシュの保存容量は課金対象ではなく上限管理されている点も押さえておきたいところです。アーティファクト(ビルド成果物の保存)は契約プランに応じて課金されますが、キャッシュは容量超過時に古いものが削除される仕組みになっています。クラウドコストを見直す際、この違いを把握していないと「キャッシュを増やせばコストが増える」と誤解しがちです。
不変性という設計を前提にキーを組む
GitHub Actionsのキャッシュは「既存のエントリの中身を書き換えることはできない」と明記されています。同じキーで2回目の保存を試みても、既存のアーカイブは置き換わりません。ジョブが生成した内容が変わっていても、キーが変わっていなければ新しい内容は保存されず、古い内容がいつまでも復元され続けます。
この性質から導かれる設計ルールはシンプルです。キャッシュ対象のディレクトリの中身に影響するすべての入力を、キー文字列に含める必要があります。OSの種類、ロックファイルのハッシュ、ツールチェーンのバージョンファイルなどが代表例です。
# 中身に影響するすべての入力をキーに含め、v2 は手動で世代を切り替えるための接頭辞
key: v2-build-${{ runner.os }}-${{ hashFiles('Cargo.lock', 'rust-toolchain.toml') }}
restore-keys: |
v2-build-${{ runner.os }}-キャッシュを明示的に破棄したいときは、削除ではなく「バージョン接頭辞を1つ進める」方法が推奨されています。古いエントリは7日ルールで自然に消えるため、削除処理を自前で書く必要がありません。
オンプレの常識が通用しない理由
オンプレ環境でJenkinsなどのCIサーバーを運用していた経験がある方ほど、Actionsのキャッシュに戸惑うことがあります。オンプレのビルドサーバーはディスクが永続し、/var/cacheのようなディレクトリが実行間でそのまま残るのが普通でした。
GitHub Actionsのホステッドランナーは毎回使い捨ての仮想マシンです。永続ディスクという概念がそもそも存在しないため、キャッシュは「ネットワーク越しに取得するアーカイブ」として再設計されています。この違いを理解せずに移行すると、「前はキャッシュが常に効いていたのに、クラウドに移行したら不安定になった」という障害報告につながりやすくなります。
根本原因は設定ミスではなく、ストレージモデルそのものの違いです。障害対応の一次切り分けでは、まず「容量超過・7日経過・スコープ不一致」の3点を疑うのが近道です。
今日から確認できること
実際のワークフローでキャッシュの状態を確認する手順は次の通りです。
- ワークフローのログで
cache-hitの値を確認する(trueなら完全一致、falseなら部分復元かミス) Cache not found for input keys:というログ行が出ていないか検索する- リポジトリの設定画面からキャッシュの使用容量と一覧を確認し、10GBに近づいていないか見る
keyにhashFilesを使っているか、固定文字列だけになっていないか設定ファイルを見直す- 週末や長期休暇明けのビルド時間が普段より長くなっていないか、CI実行時間のメトリクスを確認する
監視の観点では、CI実行時間そのものをダッシュボードに出しておくと、キャッシュ劣化の兆候を早期に捉えられます。7日ルールによる「月曜のコールドスタート」は周期的に発生するため、異常値ではなくパターンとして記録しておくと障害調査の初動が速くなります。
まとめ
GitHub Actionsのキャッシュが効かなくなる原因は、容量上限(10GB)、保持期間(7日)、ブランチスコープの3つにほぼ集約されます。どれもエラーを出さずに静かに失敗するため、ログのcache-hit出力とキー設計を定期的に見直すことが欠かせません。
まず自分のワークフローのkeyにhashFilesが含まれているか確認し、固定値だけになっていないかをチェックしてみてください。あわせてリポジトリのキャッシュ使用量画面を開き、10GBの上限にどれだけ近づいているかを見ておくと、次にビルドが急に遅くなったときの切り分けが格段に楽になります。