コンテンツへスキップ

GitHub Actionsのキャッシュキーとは?

最終更新

キャッシュキーとは、GitHub Actionsが保存済みのキャッシュを見つけるために使用する文字列です。完全に一致するキーのキャッシュが存在すればそれが復元されます。存在しない場合はステップがキャッシュミスを報告し、ジョブがデータを再構築して、そのキーで保存します。

仕組み

actions/cacheには、保存するpath、key、および任意のrestore-keysを指定します。復元時には、まず完全に一致するkeyを探します。見つからない場合は、各restore-keysのエントリをプレフィックスとして試し、それで始まる最新のキャッシュを使用します。プレフィックスが一致した場合は古いデータが復元されます。これは通常、何もないよりは望ましい状態です。そして、ジョブの最後には完全なキーで新しいキャッシュが保存されます。

キャッシュは変更できません。同じキーを上書きすることはできないため、適切なキーは、キャッシュされた内容を変更すべきタイミングでのみ変わるように設計します。一般的な方法は、ロックファイルのハッシュを使うことです。

例

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

この例では、ロックファイルが変更されるとキーも変わります。キーが変わると、restore-keysのプレフィックスによって前回のキャッシュが復元され、npmは差分だけをダウンロードし、新しいキャッシュが保存されます。

適切なキーの作り方

  1. キャッシュの内容を示す、安定したプレフィックスから始めます(npm、cargo、gradleなど)。
  2. 内容がプラットフォームに依存する場合は、runner.osとアーキテクチャを追加します。
  3. 内容を定義するファイル(ロックファイル、ビルドファイル)のhashFiles()を追加します。
  4. 意図的にキャッシュを無効化できるよう、手動のバージョン番号(v2)を追加します。

キャッシュキービルダーでは、一般的なスタック向けのキーを生成できます。全体像についてはGitHub Actionsのキャッシュをご覧ください。

よくある間違い

  • github.shaをキーにする。コミットごとに新しいキーが作られるため、キャッシュにヒットすることはありません。
  • ハッシュの対象が少なすぎる、または多すぎる。ソースファイルをハッシュすると、キーが絶えず変わってしまいます。何もハッシュしないと、キャッシュが古くなります。
  • restore-keysを指定しない。依存関係が一つ変わっただけで、差分ビルドではなく全体のリビルドが発生します。
  • スコープのルールを忘れる。ブランチで保存されたキャッシュは、そのブランチとベースブランチからは参照できますが、兄弟ブランチからは参照できません。
  • サイズ上限に達する。リポジトリには合計キャッシュサイズの上限があり、古いエントリは削除されます。キャッシュの制限をご覧ください。

よくある質問

既存のキャッシュを更新できますか?

いいえ。キーは変更できません。キーを変更(たとえばロックファイルのハッシュ経由)すると、新しいキャッシュが保存されます。

restore-keysは何をしますか?

完全一致するキーがない場合に、最も近い古いキャッシュを復元するためのフォールバック用プレフィックスを提供します。

キャッシュを消去するにはどうすればよいですか?

リポジトリのActionsキャッシュのページ、またはGitHub CLIから削除するか、キーのバージョン文字列を更新します。