GitHub Actionsのキャッシュ: キー、上限、例
最終更新日
適切なキャッシュがあれば、3分かかる依存関係のインストールが10秒で終わります。一方で不適切なキャッシュは何も節約できないか、古いファイルを復元してビルドを壊すこともあります。本ガイドでは、GitHub Actions のキャッシュが復元対象をどのように選ぶのか、キーの書き方、そして想定すべき上限について説明します。
キャッシュの2つの方法
セットアップアクションの組み込みキャッシュ。 一般的なエコシステムでは、1行で十分です:
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm # npm, yarn or pnpm
- uses: actions/setup-python@v5
with:
python-version: "3.13"
cache: pip
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
これらはロックファイルをキーとして、パッケージマネージャーのダウンロードディレクトリをキャッシュします。setup-go はデフォルトでキャッシュします。条件に合う場合はこれを使ってください。メンテナンスの必要がありません。
それ以外には actions/cache。 パスとキーは自分で指定します:
- uses: actions/cache@v4
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
restore-keys: |
gradle-${{ runner.os }}-
キーの一致の仕組み
キャッシュを検索すると、GitHub はまず key との完全一致を探します。一致しない場合は、restore-keys の各行を上から順に試し、そのプレフィックスで始まるキーのうち最も新しく作成されたキャッシュを選びます。完全一致した場合、アクションは cache-hit を true に設定し、ジョブ終了時の保存ステップをスキップします。restore-keys による部分一致の場合は、ジョブは実行され、完全な key で新しいキャッシュを保存します。
この動作こそ restore-keys の目的です。ロックファイルの依存関係が1つ変わると完全一致は外れますが、プレフィックスによって前日のキャッシュが復元されるため、インストールは差分だけを取得すれば済みます。
良いキーは3つの要素から成ります。OS とアーキテクチャ、ツールのバージョン、そして入力のハッシュです。
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}
キャッシュキービルダーで、主要なスタック向けのキーと restore-keys を生成できます。
スコープと上限
以下は、GitHub の依存関係キャッシュと利用上限に関するドキュメントに基づいています:
- ワークフローは、現在のブランチとベースブランチ(およびデフォルトブランチ)で作成されたキャッシュを復元できます。フィーチャーブランチは
mainのキャッシュを読めますが、mainはフィーチャーブランチのキャッシュを読めません。同階層のブランチ同士も互いのキャッシュを読めません。 - プルリクエストの場合、キャッシュはマージ ref に紐づくため、あるPRのキャッシュを別のPRで再利用することはできません。
- 7日間アクセスされなかったキャッシュは削除されます。
- リポジトリごとのキャッシュ容量の既定の合計は10 GB です。上限を超えると、GitHub は最も長く使われていないキャッシュから削除します。オーナーは上限を引き上げることができ、含まれる容量を超えた分は課金されます。
- キャッシュのエントリは変更できません。キーを更新することはできず、新しいキーを作成することになります。
実務上の帰結として、main でキャッシュが確実に作成されるようにしてください。main へのプッシュでも同じキャッシュステップを実行し、すべての PR がウォームなキャッシュから始まるようにします。
キャッシュする対象と、しない対象
| キャッシュ対象 | キー | キャッシュしないもの |
|---|---|---|
| npm、pnpm、yarn のダウンロードキャッシュ | package-lock.json, pnpm-lock.yaml, yarn.lock | node_modules 自体 |
| pip、Poetry、uv のダウンロードキャッシュ | requirements*.txt, poetry.lock, uv.lock | Python バージョンをまたいだ仮想環境全体 |
| Gradle、Maven | ビルドファイル、ラッパーのプロパティ | 絶対パスを含むビルド出力 |
| Cargo | Cargo.lock | 巨大なワークスペースの target/。節約できる時間より大きくなることがよくあります |
| コンパイラキャッシュ(ccache、sccache) | OS、コンパイラのバージョン | なし。これらはキャッシュする価値があります |
大きなキャッシュにはコストがかかります。ダウンロードと展開に40秒かかる2 GB のキャッシュは、30秒のインストールに勝てないかもしれません。復元時間はステップのログで計測してください。
キャッシュミスの主な原因
- キーに、実行ごとに変わる値が含まれている。例えば
github.shaやタイムスタンプです。ローリングキャッシュの場合にのみ、restore-keysと組み合わせてキーの末尾に使ってください。 hashFilesが何にも一致しない。 空文字列を返すため、すべての実行が同じキーを使い、更新されなくなります。グロブを確認してください。- OS またはアーキテクチャが異なる。
runner.osとrunner.archを含めてください。 - 保存時と復元時でパスが異なる。 パスはキャッシュの識別子の一部です。
- ブランチのスコープ。 新しいブランチが参照できるのは、自身のキャッシュとデフォルトブランチのキャッシュだけです。
- 削除(エビクション)。 リポジトリの Actions キャッシュ一覧を確認してください。ブランチが多いと、10 GB はすぐにいっぱいになります。
CLIからキャッシュを一覧表示および削除します:
gh cache list --limit 50
gh cache delete <cache-id>
ビルド出力のローリングキャッシュ
インクリメンタルコンパイラでは、各実行を前回の出力から開始し、その後新しい出力を保存することが望ましいです。一意のキーとプレフィックスによるフォールバックを使用します:
- uses: actions/cache@v4
with:
path: .turbo
key: turbo-${{ runner.os }}-${{ github.sha }}
restore-keys: |
turbo-${{ runner.os }}-
毎回の実行で完全一致のキーは見つからず、最新のプレフィックス一致を復元し、新しいエントリを保存します。このパターンでは10 GBの上限にご注意ください。古いエントリは自動的に削除されます。
復元と保存を分ける
ジョブが成功した場合のみ保存する、またはmainからのみ保存する場合は、actions/cache/restoreとactions/cache/saveを使用します:
- uses: actions/cache/restore@v4
id: cache
with:
path: ~/.m2
key: m2-${{ hashFiles('**/pom.xml') }}
- run: mvn -B verify
- uses: actions/cache/save@v4
if: github.ref == 'refs/heads/main' && steps.cache.outputs.cache-hit != 'true'
with:
path: ~/.m2
key: m2-${{ hashFiles('**/pom.xml') }}
これにより、PRブランチがクォータを使い切ることを防げます。
よくある質問
GitHub Actionsのキャッシュの最大サイズはどれくらいですか?
GitHubの利用上限に記載されているとおり、リポジトリ全体の合計は既定で10 GBです。
ワークフロー間でキャッシュを共有できますか?
キーとパスが一致し、ブランチのスコープが許可していれば可能です。キャッシュは個々のワークフローではなく、リポジトリに属します。
ここでDockerレイヤーもキャッシュすべきですか?
Dockerレイヤーには専用のバックエンドがあります。CIでのDockerレイヤーキャッシュをご覧ください。
キャッシュヒットは必ず安全ですか?
完全一致のキーでヒットした場合、そのキーで保存された内容がそのまま復元されます。安全性は、ファイルに影響するすべての入力がキーに含まれているかどうかによります。
この内容の位置づけ
キャッシュは、GitHub Actionsを高速化する方法で紹介しているいくつかの対策の一つです。キャッシュで改善しても、ジョブがまだ遅い場合は、ジョブがCPU負荷に依存しているかを確認してください。compiler.devの比較モードでは、より高速なマシンでジョブを実行するため、ご自身のワークフローで違いを確認できます。
関連記事
- Buildxを使ったCIでのDockerレイヤーキャッシュcache-fromとcache-to、ghaおよびregistryバックエンド、キャッシュヒットを狙った順序のDockerfileを使い、GitHub ActionsでのDockerビルドを高速化しましょう。
- GitHub ActionsでTypeScriptモノレポを高速化するGitHub Actionsで TypeScriptモノレポの型チェックとリンターを高速化する: インクリメンタルtsc、プロジェクト参照、Lintキャッシュ、並列ジョブ
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。
- READMEにCIの速度バッジを追加するREADME のバッジで CI の速さを表示しましょう。リポジトリの GitHub Actions 実行時間の中央値が自動で更新されます。公開リポジトリは無料です。