コンテンツへスキップ

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.locknode_modules 自体
pip、Poetry、uv のダウンロードキャッシュrequirements*.txt, poetry.lock, uv.lockPython バージョンをまたいだ仮想環境全体
Gradle、Mavenビルドファイル、ラッパーのプロパティ絶対パスを含むビルド出力
CargoCargo.lock巨大なワークスペースの target/。節約できる時間より大きくなることがよくあります
コンパイラキャッシュ(ccache、sccache)OS、コンパイラのバージョンなし。これらはキャッシュする価値があります

大きなキャッシュにはコストがかかります。ダウンロードと展開に40秒かかる2 GB のキャッシュは、30秒のインストールに勝てないかもしれません。復元時間はステップのログで計測してください。

キャッシュミスの主な原因

  1. キーに、実行ごとに変わる値が含まれている。例えば github.sha やタイムスタンプです。ローリングキャッシュの場合にのみ、restore-keys と組み合わせてキーの末尾に使ってください。
  2. hashFiles が何にも一致しない。 空文字列を返すため、すべての実行が同じキーを使い、更新されなくなります。グロブを確認してください。
  3. OS またはアーキテクチャが異なる。 runner.os と runner.arch を含めてください。
  4. 保存時と復元時でパスが異なる。 パスはキャッシュの識別子の一部です。
  5. ブランチのスコープ。 新しいブランチが参照できるのは、自身のキャッシュとデフォルトブランチのキャッシュだけです。
  6. 削除(エビクション)。 リポジトリの 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の比較モードでは、より高速なマシンでジョブを実行するため、ご自身のワークフローで違いを確認できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す