GitHub Actionsのキャッシュの上限、サイズ、削除ルール
最終更新
GitHub Actionsのキャッシュ上限は、多くのチームを驚かせます。リポジトリにはデフォルトで10 GBが割り当てられ、その容量がいっぱいになると、GitHubは古いキャッシュを削除します。その結果、理由がはっきりしないままビルドが再び遅くなることがあります。このガイドでは、上限、削除、キャッシュサイズ、pnpmとDockerに関する詳細を扱います。actions/cacheの基本については、まずキャッシュのガイドをお読みください。このガイドは、そこで終わったところから始まります。以下の数値はGitHubの依存関係キャッシュのドキュメントに基づき、2026-10-11に確認したものです。
上限の内容
- リポジトリごとの合計サイズ:すべてのキャッシュを合わせて、デフォルトでは10 GBです。オーナーや管理者はこの上限を引き上げられます。10 GBを超えた分は課金対象になります。
- 保持期間:7日間アクセスされなかったキャッシュエントリは削除されます。
- 削除:リポジトリが上限を超えている場合でも、GitHubは新しいキャッシュを保存します。その後、合計が上限を下回るまで、古いキャッシュ(最も長く使われていないもの)から順に削除します。
- キャッシュの数:数に上限はなく、制限は合計サイズのみです。
キャッシュの使用状況は、リポジトリのActionsタブ内のCachesページで確認できます。CLIではgh cache list --sort size_in_bytesを使います。
削除によってCIが遅くなる理由
削除によってキャッシュのスラッシングが起こることがあります。実行のたびに新しいキャッシュが保存され、別のキャッシュが削除され、次の実行ではそのキャッシュがミスになります。兆候としては、最近実行されたブランチのログに「Cache not found for input keys」と表示されたり、チームの規模が大きくなるにつれてヒット率が下がったりします。
よくある原因:
- コミットごとに新しいキーを作る。
${{ github.sha }}のようなキーはプッシュのたびに1つずつキャッシュを作ります。これらはすぐに10 GBを埋めてしまい、ヒットすることもありません。 - OSやマトリックスのセルごとに大きなキャッシュを重複して保存する。6個のマトリックスセルに700 MBずつ保存すると、合計4.2 GBになります。
- lockfileの変更のたびに内容が変わる
node_modulesやビルドディレクトリをキャッシュする。変更のたびに、新しいフルコピーが1つずつ追加されます。 - ブランチによるスコープ。ワークフローは、現在のブランチ、ベースブランチ、またはデフォルトブランチで作られたキャッシュを復元できますが、兄弟ブランチで作られたキャッシュは復元できません。プルリクエストのキャッシュはマージ参照に対して作られるため、あるPRで作られたキャッシュは別のPRからは見えません。デフォルトブランチのキャッシュを温めておけば、全員がそこから復元できます。たとえば、スケジュールされたジョブを使います(cronスケジュールを参照)。
対処法
ヒットするキー
- uses: actions/cache@v4
with:
path: ~/.cache/pip
key: pip-${{ runner.os }}-${{ hashFiles('**/requirements*.txt') }}
restore-keys: |
pip-${{ runner.os }}-
コミットではなくlockfileでキーを作ります。restore-keysを使うと、部分一致で最も新しい類似キャッシュを復元でき、その後、正確なキーで新しいキャッシュが保存されます。キャッシュキービルダーでこれらを生成できます。
保存量を減らし、一度だけ保存する
- 可能であれば、インストール済みのツリーではなく、パッケージマネージャーのダウンロードキャッシュをキャッシュします。サイズが小さくなり、Nodeや Pythonのバージョンをまたいで再利用できます。
- ほとんどのジョブでは
actions/cache/restoreを使い、1つのジョブだけ(例えばmainへのプッシュ時)でactions/cache/saveを使います。こうすると、PRの実行は読み取りのみを行い、それぞれが新しいエントリを書き込むことはありません。 - デフォルトブランチ用の空き容量を確保するため、PRのクローズ時に
gh cache deleteで古いキャッシュを削除します。
- uses: actions/cache/restore@v4
with: { path: ~/.cache/pip, key: pip-${{ hashFiles('requirements.txt') }} }
保存前にキャッシュサイズを確認する
大きなエントリは保存と復元に時間がかかります。復元の時間が、置き換えようとしているインストールよりも長くかかるなら、そのキャッシュは破棄してください。ネットワーク経由で1.5 GBを復元すると、高速なパッケージインストールより時間がかかることがあり、「GitHub Actionsのキャッシュが遅い」と感じる一般的な理由になっています。
cache v4に関する注意
actions/cache@v4は、GitHubのより新しいキャッシュサービスを使います。GitHubは、旧キャッシュバックエンドを使う古いアクションのバージョンを非推奨にしたため、古いバージョンを固定している場合は失敗することがあります。ワークフローで古いバージョンを使っている場合は、@v4にアップグレードしてください。v4では、cache-hitが出力として公開されます。これは完全一致したキーの場合にのみtrueになり、node_modulesをキャッシュしているときに、npm ciなどのステップをスキップするのに使えます。最新の入力については、アクションのREADMEを確認してください。
pnpmの詳細
pnpmは、内容アドレス指定のストアを1つ保持し、ファイルをnode_modulesへハードリンクします。キャッシュするのはnode_modulesではなくストアです。
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
setup-nodeでcache: pnpmを指定すると、pnpm-lock.yamlをキーとしてストアをキャッシュします。手動でキャッシュする場合は、pnpm store pathでパスを取得します。ストアを復元してpnpm install --frozen-lockfile --prefer-offlineを実行すると、ファイルのリンクだけで済むため、通常は素早く完了します。モノレポでは、lockfileが1つなのでキーも1つになり、キャッシュの数を少なく保てます。
Dockerイメージのキャッシュ
actions/cacheでDockerのレイヤーをキャッシュすると、数GBを消費し、10 GBの上限に達することがあります。選択肢は次のとおりです。
- Buildxの
type=ghaキャッシュは、レイヤーを同じキャッシュサービスに保存し、同じ上限に含まれます。サイズが問題になる場合は、mode=maxではなくmode=minを使うと、最終イメージのレイヤーだけを保存できます。 - レジストリキャッシュ(
type=registry)を使うと、代わりにコンテナレジストリにレイヤーを保存でき、10 GBの上限の対象外になります。 - Dockerfileの順序を整えると、依存関係のレイヤーをソースのコピーより前に置けるため、コストの高いレイヤーがめったに変わらなくなります。
- uses: docker/build-push-action@v6
with:
cache-from: type=gha
cache-to: type=gha,mode=min
その他のオプションはCIでのDockerレイヤーキャッシュにあります。
キャッシュの保存には費用がかかりますか?
デフォルトの上限内であれば、追加料金はかかりません。上限の10 GBを超えて増やすと、超過した分のストレージに課金されます。他の費用項目についてはGitHub Actionsの料金の解説を、料金計算ツールもあわせてご覧ください。
キャッシュが解決策にならない場合
キャッシュが大きく、復元に時間がかかる場合は、キーを調整するよりも、ローカルの永続ディスクや高速なネットワークを持つランナーのほうが効果的かもしれません。比較については高速なGitHub Actionsランナーをご覧ください。その他の対策は、高速化のガイドとCIの遅さに関するハブにあります。
よくある質問
GitHub Actionsのキャッシュサイズの上限はどれくらいですか?
デフォルトでは、リポジトリごとに全キャッシュ合わせて10 GBです。管理者が上限を引き上げることができ、10 GBを超える使用量は課金されます。
GitHubはキャッシュをどれくらいの期間保持しますか?
7日間アクセスされなかったエントリは削除されます。また、リポジトリがサイズ上限を超えた場合にも、エントリは削除されます。
GitHub Actionsのキャッシュが復元されないのはなぜですか?
キーが一致しているか、読み取り可能なブランチで作成されたキャッシュか、削除されていないか、そしてactions/cache@v4を使用しているかを確認してください。
pnpmのnode_modulesをキャッシュすべきですか?
代わりに、setup-nodeをcache: pnpmとともに使用して、pnpmストアをキャッシュしてください。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。