cache アクションの使用
cache アクションにより、キャッシュの復元時に次のシーケンスが試行されます。
- まず、指定した
keyと完全と一致するものが検索されます。 - 完全一致が見つからない場合は、
keyの部分一致が検索されます。 - それでも一致するものが見つからず、
restore-keysを指定した場合、これらのキーに部分一致がないか順番にチェックされます。 詳しくは、「キャッシュ キーの照合」をご覧ください。
指定した key との完全な一致があった場合は、キャッシュ ヒットと見なされます。 指定した key と完全に一致するキャッシュがなかった場合は、キャッシュ ミスと見なされます。 キャッシュ ミスの場合は、ジョブが正常に完了すると、このアクションによって新しいキャッシュが自動的に作成されます。 新しいキャッシュでは、指定した key が使用され、path で指定したファイルが含められます。 この処理方法について詳しくは、「キャッシュ ヒットとキャッシュ ミス」をご覧ください。
既存のキャッシュの内容を変更することはできません。 代わりに、新しいキーを使って新しいキャッシュを作成できます。
cache アクションの入力パラメーター
-
key: 必須 キャッシュの保存時に作成されたキーと、キャッシュの検索に使用されるキー。 変数、コンテキスト値、静的な文字列、関数の任意の組み合わせが使えます。 キーの長さは最大で512文字であり、キーが最大長よりも長いとアクションは失敗します。 -
path: 必須 キャッシュまたは復元するランナー上のパス。-
1 つのパスを指定することも、複数のパスを別々の行に追加することもできます。 たとえば次のような点です。
- name: Cache Gradle packages uses: actions/cache@v4 with: path: | ~/.gradle/caches ~/.gradle/wrapper -
ディレクトリまたは単一ファイルのいずれかを指定できます。glob パターンがサポートされています。
-
絶対パス、またはワークスペース ディレクトリに対する相対パスを指定できます。
-
-
restore-keys: オプション 代替の復元キーを含んだ文字列。各復元キーは新しい行に配置されます。keyに対するキャッシュ ヒットが発生しない場合は、キャッシュを検索して復元するために、これらの復元キーが指定された順序で使用されます。 たとえば次のような点です。restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- -
enableCrossOsArchive: 省略可能 ブール値。有効の場合、キャッシュが作成されたオペレーティング システムに関係なく、Windows ランナーがキャッシュを保存または復元できます。 このパラメーターが設定されていない場合、既定値はfalseになります。 詳しくは、Actions Cache に関するドキュメントの「Cross OS cache (クロス OS キャッシュ)」を参照してください。
メモ
アクセス トークンやログイン資格情報などの機密情報は、キャッシュ パス内のファイルに保存しないことをお勧めします。 読み取りアクセスを持つ人は誰でも、リポジトリに pull request を作成し、キャッシュの内容にアクセスできます。 さらに、リポジトリのフォークでベース ブランチに pull request を作成し、ベース ブランチ上のキャッシュにアクセスできます。
cache アクションの出力パラメーター
cache-hit: キーに対して完全一致が見つかったかどうかを示すブール値。
キャッシュ ヒットとキャッシュ ミス
key が既存のキャッシュと厳密に一致した場合、それは "キャッシュ ヒット" と呼ばれ、アクションによってキャッシュされたファイルが path ディレクトリに復元されます。
key が既存のキャッシュと一致しない場合 (これは キャッシュ ミス と呼ばれます)、ジョブが正常に完了すると、新しいキャッシュが作成されます。
キャッシュ ミスが発生した場合、アクションはユーザーが指定した restore-keys の一致も検索します。
restore-keysを指定した場合、cacheアクションはrestore-keysのリストに一致するすべてのキャッシュを順次検索します。- 完全に一致する場合、アクションはキャッシュ内のファイルを
pathディレクトリに復元します。 - 完全なマッチがなかった場合、アクションはリストアキーに対する部分一致を検索します。 アクションで部分的な一致が見つかると、最新のキャッシュが
pathディレクトリに復元されます。
- 完全に一致する場合、アクションはキャッシュ内のファイルを
cacheアクションが完了し、ジョブの次のステップが実行されます。- ジョブが正常に完了すると、アクションは
pathディレクトリのコンテンツを含んだ新しいキャッシュを自動的に作成します。
キャッシュ照合プロセスについて詳しくは、「キャッシュ キーの照合」をご覧ください。
cache アクションの使用例
次の例では、package-lock.json ファイル内のパッケージが変更されたとき、またはランナーのオペレーティング システムが変更されたときに、新しいキャッシュを作成します。 キャッシュ キーは、コンテキストと式を使用して、ランナーのオペレーティング システムと package-lock.json ファイルの SHA-256 ハッシュを含むキーを生成します。
name: Caching with npm
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Cache node modules
id: cache-npm
uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
# npm cache files are stored in `~/.npm` on Linux/macOS
path: ~/.npm
key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-build-${{ env.cache-name }}-
${{ runner.os }}-build-
${{ runner.os }}-
- if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
name: List the state of node modules
continue-on-error: true
run: npm list
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
- name: Test
run: npm test
name: Caching with npm
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Cache node modules
id: cache-npm
uses: actions/cache@v4
env:
cache-name: cache-node-modules
with:
# npm cache files are stored in `~/.npm` on Linux/macOS
path: ~/.npm
key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-build-${{ env.cache-name }}-
${{ runner.os }}-build-
${{ runner.os }}-
- if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
name: List the state of node modules
continue-on-error: true
run: npm list
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
- name: Test
run: npm test
コンテキストを使ったキャッシュキーの作成
キャッシュキーには、コンテキスト、関数、リテラル、GitHub Actionsがサポートする演算子を含めることができます。 詳細については、「コンテキスト リファレンス」および「ワークフローとアクションで式を評価する」を参照してください。
式を使用して key を作成すると、依存関係が変更されたときに新しいキャッシュを自動的に作成できます。
たとえば、npm package-lock.json ファイルのハッシュを計算する式を使用して key を作成できます。 その場合、package-lock.json ファイルを構成する依存関係が変更されると、キャッシュ キーが変更され、新しいキャッシュが自動的に作成されます。
npm-${{ hashFiles('package-lock.json') }}
GitHub は、式 hash "package-lock.json" を評価して最終的な key を導き出します。
npm-d5ea0750
cache アクションの出力の使用
cache アクションの出力を使用すると、キャッシュ ヒットやキャッシュ ミスが発生したどうかに基づいて操作を実行することができます。 指定した key のキャッシュに完全一致が見つかった場合、cache-hit の出力は true に設定されます。
上記のワークフロー例では、キャッシュ ミスが発生した場合に、Node モジュールの状態をリストする手順があります。
- if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
name: List the state of node modules
continue-on-error: true
run: npm list
キャッシュ キーの照合
cache アクションは、最初にワークフロー実行を含むブランチで、key とキャッシュ "バージョン" のキャッシュ ヒットを検索します。 見つからない場合は、key のプレフィックス一致が検索されます。それでも見つからない場合は、restore-keys と "バージョン" が検索されます。__ それでも Current Branch 内に見つからない場合、cache アクションにより、既定のブランチに対して同じ手順が再試行されます。 検索中はスコープの制限が適用されることに注意してください。 詳しくは、「キャッシュへのアクセスについての制限」をご覧ください。
キャッシュ バージョンは、キャッシュの作成時に使用された path と圧縮ツールのメタデータを使って、キャッシュにスタンプを付ける方法です。 これにより、使用するワークフロー実行が、実際に圧縮を解除して使用できるキャッシュと一意に一致することが保証されます。 詳しくは、Actions Cache に関するドキュメントの「Cache Version (キャッシュ バージョン)」を参照してください。
restore-keys では、key でキャッシュ ミスが発生した場合に使用する代替復元キーのリストを指定できます。 特定の度合いが強いものから弱いものへ並べて複数のリストアキーを作成できます。 cache アクションは restore-keys を順番に検索します。 キーが直接マッチしなかった場合、アクションはリストアキーでプレフィックスされたキーを検索します。 リストアキーに対して複数の部分一致があった場合、アクションは最も最近に作成されたキャッシュを返します。
複数のリストアキーの利用例
restore-keys: |
npm-feature-${{ hashFiles('package-lock.json') }}
npm-feature-
npm-
ランナーは式を評価し、次の restore-keys に解決します。
restore-keys: |
npm-feature-d5ea0750
npm-feature-
npm-
復元キー npm-feature- は、文字列 npm-feature- で始まるすべてのキーと一致します。 たとえば、npm-feature-fd3052de および npm-feature-a9b253ff の両方のキーと復元キーが一致します。 最も最近の期日に作成されたキャッシュが使われます。 この例でのキーは、以下の順序で検索されます。
npm-feature-d5ea0750は特定のハッシュと一致します。npm-feature-はnpm-feature-というプレフィックスが付いたキャッシュ キーと一致します。npm-はnpm-というプレフィックスが付いたすべてのキーと一致します。
検索の優先度の例
key:
npm-feature-d5ea0750
restore-keys: |
npm-feature-
npm-
たとえば、pull request が feature ブランチを含んでいて、既定のブランチ (main) をターゲットとしている場合、アクションは key と restore-keys を次の順序で検索します。
featureブランチ内npm-feature-d5ea0750のキーfeatureブランチ内のキーnpm-feature-featureブランチ内のキーnpm-mainブランチ内のキーnpm-feature-d5ea0750mainブランチ内のキーnpm-feature-mainブランチ内のキーnpm-
特定のパッケージ マネージャーに対する setup-* アクション
以下の一覧で示すパッケージ マネージャーをキャッシュする場合、それぞれの setup-* アクションを使うには最小構成が必要であり、依存関係キャッシュの作成と復元は自動的に行われます。
| パッケージ マネージャー | キャッシュの setup-* アクション |
|---|---|
| npm、Yarn、pnpm | setup-node |
| pip、pipenv、Poetry | setup-python |
| Gradle、Maven | setup-java |
| RubyGems | setup-ruby |
Go go.sum | setup-go |
| .NET NuGet | setup-dotnet |
キャッシュへのアクセスについての制限
アクセス制限を使用すると、さまざまなブランチまたはタグ間に論理境界を作成することで、キャッシュを分離しセキュリティで保護することができます。
ワークフロー実行では、現在のブランチまたは既定のブランチ (通常は main) で作成されたキャッシュを復元できます。 pull request に対してワークフロー実行がトリガーされた場合は、ベース ブランチで作成されたキャッシュを復元することもできます (フォークされたリポジトリのベース ブランチも含む)。 たとえば、ブランチ feature-b にベース ブランチ feature-a がある場合、pull request でトリガーされたワークフロー実行では、既定のブランチ main、ベース ブランチ feature-a、および現在のブランチ feature-b で作成されたキャッシュにアクセスできます。
ワークフロー実行では、子ブランチまたは兄弟ブランチ用に作成されたキャッシュを復元することはできません。 たとえば、子ブランチ feature-b 用に作成されたキャッシュに、親ブランチ main でトリガーされたワークフロー実行からアクセスすることはできません。 同様に、ベース main を持つブランチ feature-a 用に作成されたキャッシュに、ベース main を持つその兄弟ブランチ feature-c からアクセスすることはできません。 また、ワークフロー実行では、異なるタグ名に対して作成されたキャッシュを復元することもできません。 たとえば、タグ release-a に対してベース main で作成されたキャッシュに、タグ release-b に対してベース main でトリガーされたワークフロー実行からアクセスすることはできません。
pull request でトリガーされたワークフロー実行によってキャッシュが作成される場合、そのキャッシュは merge ref (refs/pull/.../merge) に対して作成されます。 このため、このキャッシュのスコープは制限され、pull request の再実行によってのみ復元できます。 ベース ブランチ、またはそのベース ブランチを対象とする他の pull request では、復元できません。
リポジトリ内の複数のワークフロー実行で、キャッシュを共有できます。 あるワークフロー実行でブランチ用に作成されたキャッシュは、同じリポジトリとブランチの別のワークフロー実行からアクセスおよび復元できます。
メモ
オブジェクトはランナーから直接キャッシュから取得されるかキャッシュに格納されるため、アクション ランナーは、AWS S3 や Azure Blob Storage など、GitHub Enterprise Server で構成された Actions オブジェクト ストレージに直接接続する必要があります。 セルフホステッド ランナーは、GitHub Enterprise Server インスタンスによって提供されるアクセス URL を使って、BLOB ストレージ プロバイダーで認証します。 この URL は、BLOB ストレージ プロバイダーに有効かつ一時的な認証資格情報を提供します。 このプロセスはインスタンス自体によって開始され、オブジェクト ストレージへのすべての要求を仲介します。
これは、actions/cache が正しく機能するには、BLOB ストレージへの HTTPS 接続が必要であることを意味します。
すべてのメタデータは、GitHub Actions 内のマイクロサービスである成果物キャッシュ サービスによって管理されます。
キャッシュ ストレージの詳細については、「外部ストレージの要件」を参照してください。
利用制限と退去のポリシー
GitHubは、7日間以上アクセスされていないキャッシュエントリを削除します。 格納できるキャッシュの数に制限はありませんが、リポジトリ内のすべてのキャッシュの合計サイズは制限されています。 既定では、リポジトリあたり 10 GB の制限ですが、この制限は、エンタープライズ所有者やリポジトリ管理者が設定したポリシーによって変わる場合があります。 リポジトリが最大キャッシュ ストレージに達すると、キャッシュの削除ポリシーにより、最終アクセス日時が最も古いものから最も新しいものの順にキャッシュが削除されて、スペースが作成されます。
この制限を超えると、GitHub は新しいキャッシュを保存しますが、合計サイズがリポジトリの制限を下回るまでキャッシュの削除を開始します。キャッシュの削除プロセスが原因でキャッシュのスラッシングが発生する場合があり、キャッシュの作成と削除が高い頻度で行われます。 これを軽減するには、リポジトリのキャッシュを確認し、修正手順を実行できます (特定のワークフローからキャッシュを削除するなど)。 「キャッシュの管理」をご覧ください。リポジトリのキャッシュ サイズ制限を増やすこともできます。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。
次のステップ
依存関係キャッシュの管理については、「キャッシュの管理」をご覧ください。