# 依存関係キャッシュのリファレンス ワークフローでの依存関係キャッシュの機能について説明します。 ## `cache` アクションの使用 [ `cache`アクション](https://github.com/actions/cache)は、キャッシュの復元時に次のシーケンスを試行します。 1. まず、指定した `key` との完全一致が検索されます。 2. 完全一致が見つからない場合は、`key` の部分一致が検索されます。 3. それでも一致が見つからず、`restore-keys` を指定した場合、これらのキーに部分一致がないか順番にチェックされます。 詳細については、[「キャッシュ キーの一致」](#cache-key-matching)を参照してください。 指定した `key` との完全な一致があった場合は、キャッシュ ヒットと見なされます。 指定した `key` と完全に一致するキャッシュがなかった場合は、キャッシュ ミスと見なされます。 キャッシュ ミスの場合は、ジョブが正常に完了すると、このアクションによって新しいキャッシュが自動的に作成されます。 新しいキャッシュでは、指定した `key` が使用され、`path` で指定したファイルが含められます。 処理方法の詳細については、[「キャッシュ ヒットとキャッシュ ミス」](#cache-hits-and-misses)を参照してください。 既存のキャッシュの内容を変更することはできません。 代わりに、新しいキーを使って新しいキャッシュを作成できます。 ### `cache` アクションの入力パラメーター * `key`: **必須** キャッシュ保存時に作成されたキーとキャッシュ検索時に使用されるキー。 変数、コンテキスト値、静的な文字列、関数の任意の組み合わせが使えます。 キーの長さは最大で512文字であり、キーが最大長よりも長いとアクションは失敗します。 * `path`: **必須** キャッシュまたは復元するためのランナーのパス。 * 1 つのパスを指定することも、複数のパスを別々の行に追加することもできます。 次に例を示します。 ```yaml - name: Cache Gradle packages uses: actions/cache@v4 with: path: | ~/.gradle/caches ~/.gradle/wrapper ``` * ディレクトリまたは単一ファイルのいずれかを指定できます。glob パターンがサポートされています。 * 絶対パス、またはワークスペース ディレクトリに対する相対パスを指定できます。 * `restore-keys`: **オプション** 代替の復元キーを含んだ文字列。各復元キーは新しい行に配置されます。 `key` に対するキャッシュ ヒットが発生しない場合は、キャッシュを検索して復元するために、これらの復元キーが指定された順序で使用されます。 次に例を示します。 ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` * `enableCrossOsArchive`: **Optional** 有効にすると、キャッシュが作成されたオペレーティング システムとは別に、Windows ランナーがキャッシュを保存または復元できるようにするブール値。 このパラメーターが設定されていない場合、既定値は `false` になります。 詳しくは、Actions Cache に関するドキュメントの「[Cross OS cache (クロス OS キャッシュ)](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cross-os-cache)」を参照してください。 > \[!NOTE] > アクセス トークンやログイン資格情報などの機密情報は、キャッシュ パス内のファイルに保存しないことをお勧めします。 読み取りアクセスを持つ人は誰でも、リポジトリに pull request を作成し、キャッシュの内容にアクセスできます。 さらに、リポジトリのフォークも、ベース ブランチ上に pull request を作成し、ベース ブランチ上のキャッシュにアクセスできます。 ### `cache` アクションの出力パラメーター * `cache-hit`: キーに対して完全一致が見つかったかどうかを示すブール値。 ### キャッシュ ヒットとキャッシュ ミス `key` が既存のキャッシュと厳密に一致した場合、それは "*キャッシュ ヒット*" と呼ばれ、アクションによってキャッシュされたファイルが `path` ディレクトリに復元されます。 `key` が既存のキャッシュと一致しない場合 (これは *キャッシュ ミス* と呼ばれます)、ジョブが正常に完了すると、新しいキャッシュが作成されます。 キャッシュ ミスが発生した場合、アクションはユーザーが指定した `restore-keys` の一致も検索します。 1. `restore-keys` を指定した場合、`cache` アクションは `restore-keys` のリストに一致するすべてのキャッシュを順次検索します。 * 完全に一致する場合、アクションはキャッシュ内のファイルを `path` ディレクトリに復元します。 * 完全なマッチがなかった場合、アクションはリストアキーに対する部分一致を検索します。 アクションで部分的な一致が見つかると、最新のキャッシュが `path` ディレクトリに復元されます。 2. `cache` アクションが完了し、ジョブの次のステップが実行されます。 3. ジョブが正常に完了すると、アクションは `path` ディレクトリのコンテンツを含んだ新しいキャッシュを自動的に作成します。 キャッシュ一致プロセスの詳細については、[「キャッシュ キーの一致」](#cache-key-matching)を参照してください。 ### `cache` アクションの使用例 次の例では、`package-lock.json` ファイル内のパッケージが変更されたとき、またはランナーのオペレーティング システムが変更されたときに、新しいキャッシュを作成します。 キャッシュ キーは、コンテキストと式を使用して、ランナーのオペレーティング システムと `package-lock.json` ファイルの SHA-256 ハッシュを含むキーを生成します。 ```yaml copy name: Caching with npm on: push jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - 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でサポートされているコンテキスト、関数、リテラル、および演算子のいずれかを含めることができます。 詳細については、「[コンテキスト リファレンス](/ja/actions/learn-github-actions/contexts)」および「[ワークフロー内とアクション内で式を評価する](/ja/actions/learn-github-actions/expressions)」を参照してください。 式を使用して `key` を作成すると、依存関係が変更されたときに新しいキャッシュを自動的に作成できます。 たとえば、npm `key` ファイルのハッシュを計算する式を使用して `package-lock.json` を作成できます。 その場合、`package-lock.json` ファイルを構成する依存関係が変更されると、キャッシュ キーが変更され、新しいキャッシュが自動的に作成されます。 ```yaml npm-${{ hashFiles('package-lock.json') }} ``` GitHub は、式 `hash "package-lock.json"` を評価して最終的な `key`を派生させます。 ```yaml npm-d5ea0750 ``` ### `cache` アクションの出力の使用 `cache` アクションの出力を使用すると、キャッシュ ヒットやキャッシュ ミスが発生したどうかに基づいて操作を実行することができます。 指定した `key` のキャッシュに完全一致が見つかった場合、`cache-hit` の出力は `true` に設定されます。 上記のワークフロー例では、キャッシュ ミスが発生した場合に、Node モジュールの状態をリストする手順があります。 ```yaml - 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` と\_バージョン\_を検索します。 それでも現在のブランチでヒットが見つからない場合、`cache` アクションは、既定のブランチで同じ手順を再試行します。 検索中はスコープの制限が適用されることに注意してください。 詳細については、[「キャッシュにアクセスする際の制限」](#restrictions-for-accessing-a-cache)を参照してください。 キャッシュ バージョンは、キャッシュの作成時に使用された `path` と圧縮ツールのメタデータを使って、キャッシュにスタンプを付ける方法です。 これにより、使用するワークフロー実行が、実際に圧縮を解除して使用できるキャッシュと一意に一致することが保証されます。 詳しくは、Actions Cache に関するドキュメントの「[Cache Version (キャッシュ バージョン)](https://github.com/actions/cache#cache-version)」を参照してください。 `restore-keys` では、`key` でキャッシュ ミスが発生した場合に使用する代替復元キーのリストを指定できます。 特定の度合いが強いものから弱いものへ並べて複数のリストアキーを作成できます。 `cache` アクションは `restore-keys` を順番に検索します。 キーが直接マッチしなかった場合、アクションはリストアキーでプレフィックスされたキーを検索します。 リストアキーに対して複数の部分一致があった場合、アクションは最も最近に作成されたキャッシュを返します。 ### 複数のリストアキーの利用例 ```yaml restore-keys: | npm-feature-${{ hashFiles('package-lock.json') }} npm-feature- npm- ``` ランナーは式を評価し、次の `restore-keys` に解決します。 ```yaml restore-keys: | npm-feature-d5ea0750 npm-feature- npm- ``` 復元キー `npm-feature-` は、文字列 `npm-feature-` で始まるすべてのキーと一致します。 たとえば、`npm-feature-fd3052de` および `npm-feature-a9b253ff` の両方のキーと復元キーが一致します。 最も最近の期日に作成されたキャッシュが使われます。 この例でのキーは、以下の順序で検索されます。 1. \*\* `npm-feature-d5ea0750` \*\* は特定のハッシュと一致します。 2. \*\* `npm-feature-` \*\* は、`npm-feature-` というプレフィックスのキャッシュ キーと一致します。 3. \*\* `npm-` \*\* は、`npm-` というプレフィックスの任意のキーと一致します。 #### 検索の優先度の例 ```yaml key: npm-feature-d5ea0750 restore-keys: | npm-feature- npm- ``` たとえば、pull request が `feature` ブランチを含んでいて、既定のブランチ (`main`) をターゲットとしている場合、アクションは `key` と `restore-keys` を次の順序で検索します。 1. `npm-feature-d5ea0750` ブランチ内のキー `feature` 2. `npm-feature-` ブランチ内のキー `feature` 3. `npm-` ブランチ内のキー `feature` 4. `npm-feature-d5ea0750` ブランチ内のキー `main` 5. `npm-feature-` ブランチ内のキー `main` 6. `npm-` ブランチ内のキー `main` ## 特定のパッケージ マネージャ向け `setup-*` アクション 以下に示すパッケージ マネージャーをキャッシュする場合、それぞれの setup-\* アクションを使用するには、最小構成が必要となります。これにより、依存関係キャッシュが作成され、復元されます。 | パッケージ マネージャー | キャッシュの setup-\* アクション | | ------------------------------------------------------------------------------------------------- | --------------------- | | npm、Yarn、pnpm | | | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) | | | pip、pipenv、Poetry | | | [setup-python](https://github.com/actions/setup-python#caching-packages-dependencies) | | | Gradle、Maven | | | [setup-java](https://github.com/actions/setup-java#caching-packages-dependencies) | | | RubyGems | | | [setup-ruby](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically) | | | 開始 `go.sum` | | | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) | | | .NET NuGet | | | [setup-dotnet](https://github.com/actions/setup-dotnet?tab=readme-ov-file#caching-nuget-packages) | | ## キャッシュへのアクセスについての制限 アクセス制限を使用すると、さまざまなブランチまたはタグ間に論理境界を作成することで、キャッシュを分離しセキュリティで保護することができます。 ワークフロー実行では、現在のブランチまたは既定のブランチ (通常は `main`) で作成されたキャッシュを復元できます。 pull request に対してワークフロー実行がトリガーされた場合は、ベース ブランチで作成されたキャッシュを復元することもできます (フォークされたリポジトリのベース ブランチも含む)。 たとえば、ブランチ `feature-b` にベース ブランチ `feature-a` がある場合、pull request でトリガーされたワークフロー実行では、既定のブランチ `main`、ベース ブランチ `feature-a`、および現在のブランチ `feature-b` で作成されたキャッシュにアクセスできます。 ワークフロー実行では、子ブランチまたは兄弟ブランチ用に作成されたキャッシュを復元することはできません。 たとえば、子ブランチ `feature-b` 用に作成されたキャッシュに、親ブランチ `main` でトリガーされたワークフロー実行からアクセスすることはできません。 同様に、ベース `feature-a` を持つブランチ `main` 用に作成されたキャッシュに、ベース `feature-c` を持つその兄弟ブランチ `main` からアクセスすることはできません。 また、ワークフロー実行では、異なるタグ名に対して作成されたキャッシュを復元することもできません。 たとえば、タグ `release-a` に対してベース `main` で作成されたキャッシュに、タグ `release-b` に対してベース `main` でトリガーされたワークフロー実行からアクセスすることはできません。 pull request でトリガーされたワークフロー実行によってキャッシュが作成される場合、そのキャッシュは merge ref (`refs/pull/.../merge`) に対して作成されます。 このため、このキャッシュのスコープは制限され、pull request の再実行によってのみ復元できます。 ベース ブランチ、またはそのベース ブランチを対象とする他の pull request では、復元できません。 リポジトリ内の複数のワークフロー実行で、キャッシュを共有できます。 あるワークフロー実行でブランチ用に作成されたキャッシュは、同じリポジトリとブランチの別のワークフロー実行からアクセスおよび復元できます。 ## 信頼レベルの低いワークフロー トリガーのキャッシュ アクセス 一部のワークフローは、フォーク プル要求や問題コメントなど、リポジトリへの書き込みアクセス権を持たないユーザーが開始できるイベントに応答して実行されます。 これらのイベントが既定のブランチのコンテキストで実行されると、後でより特権の高いワークフローが復元および信頼する悪意のあるキャッシュを書き込むのに使用できます。 このクラスの攻撃はキャッシュ \_ポイズニング\_と呼ばれます。 このリスクを軽減するために、既定のブランチのスコープでキャッシュを作成または上書きできるのは、次のワークフロー トリガーだけです。 * `push` * `workflow_dispatch` * `repository_dispatch` * `delete` * `registry_package` * `page_build` * `schedule` 既定のブランチに解決されるその他のイベントによってトリガーされる実行には、既定のブランチのスコープ内のキャッシュへの読み取り専用アクセス権が付与されます。 これらの実行は既存のキャッシュを復元できますが、作成または上書きすることはできません。 これには、ペイロードまたは開始アクターがリポジトリの外部のユーザー ( `pull_request_target`、 `issue_comment`、 `workflow_run`など) によって影響を受ける可能性があるトリガーが含まれます。 `pull_request` イベントは影響を受けません。 `pull_request`実行によって作成されたキャッシュは既にマージ ref (`refs/pull/.../merge`) のスコープであり、既定のブランチのスコープに書き込むことはできません。 詳細については、[「キャッシュにアクセスする際の制限」](#restrictions-for-accessing-a-cache)を参照してください。 読み取り専用キャッシュ アクセスを使用した実行でキャッシュを保存しようとすると、保存は失敗しますが、ステップとジョブは保存されません。 ワークフローは続行され、エラーはワークフロー ログに警告として報告されます。 その場合は、次の点を考慮してください。 * 既定のブランチ スコープでキャッシュのパフォーマンス上の利点を維持するには、キャッシュを更新し続ける信頼されたワークフロー (たとえば、既定のブランチに対する `push` によってトリガーされる CI ビルド) があることを確認します。 これらのキャッシュ エントリは、 `pull_request_target`などの低信頼イベントによってトリガーされるワークフローによって復元できます。 * 信頼度の低いワークフローでは、 `actions/cache/restore` などの復元専用のキャッシュ操作に切り替えて、目的のキャッシュの使用状況を明確にし、ワークフロー実行ログの警告を回避します。 ## キャッシュを安全に使用するためのベスト プラクティス キャッシュの内容は署名も検証もされず、キャッシュを読み取ることができるワークフロー実行では、その内容が抽出される可能性があります。 抽出されたキャッシュは、その後ワークフロー実行で実行されるファイルを変更し、悪意のあるコードが実行される可能性があります。 キャッシュを使用する場合のセキュリティ リスクを軽減するには、次のプラクティスに従います。 * **機密情報をキャッシュに格納しないでください。** リポジトリに対して pull request を開くことができるすべてのユーザーは、ベース ブランチ内のキャッシュの内容を読み取ることができます。 キャッシュされたパスにシークレット、トークン、または資格情報を書き込むことはありません。 代わりに機密値をシークレットとして格納します。 「[シークレット](/ja/actions/concepts/security/secrets)」を参照してください。 * **信頼されたトリガーからキャッシュを保存します。** 信頼されたアクター (通常はリポジトリへの書き込みアクセス権を持つもの) によってトリガーされるワークフローへのキャッシュ書き込みを制限します。 キャッシュに書き込むことができるワークフロー トリガーを制限するために適用される既定の制限については、 [低信頼ワークフロー](#cache-access-for-low-trust-workflow-triggers) トリガーのキャッシュ アクセスを参照してください。 さらに、デプロイ保護規則がある環境を使用して、キャッシュを変更できるワークフローをさらに制限することを検討してください。 「[デプロイメント用の環境管理](/ja/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)」を参照してください。 * **ワークフローのベスト セキュリティ プラクティスに従って、ワークフローを強化します。** キャッシュ/書き込みアクセス権を持つワークフローを、ワークフローの脆弱性に対して強化されたワークフローに制限します。 [セキュリティで保護された使用に関するリファレンス](/ja/actions/reference/security/secure-use#writing-workflows) のガイダンスに従って、コードの実行や悪意のあるキャッシュ エントリの導入につながる可能性のあるワークフローの脆弱性を防ぎます。 ワークフローのセキュリティ保護に関するより広範なガイダンスについては、 [セキュリティで保護された使用に関するリファレンス](/ja/actions/reference/security/secure-use) を参照してください。 ## 利用制限と退去のポリシー GitHub は、キャッシュ ストレージとリテンション期間に制限を適用してストレージ コストを管理し、不正使用を防ぎます。 これらの制限を理解することは、キャッシュの使用を最適化するのに役立ちます。 ### 既定の制限 GitHub では、7 日間にわたってアクセスされていないキャッシュ エントリが削除されます。 格納できるキャッシュの数に制限はありませんが、リポジトリ内のすべてのキャッシュの合計サイズは制限されています。 既定では、この制限はリポジトリあたり 10 GB ですが、この制限はエンタープライズ所有者、組織の所有者、またはリポジトリ管理者が増やすことができます。 10 GB を超える使用量は、アカウントに課金されます。 リポジトリが最大キャッシュ ストレージに達すると、キャッシュの削除ポリシーにより、最終アクセス日時が最も古いものから最も新しいものの順にキャッシュが削除されて、スペースが作成されます。 この制限を超えると、GitHub は新しいキャッシュを保存しますが、合計サイズがリポジトリの制限を下回るまでキャッシュの削除を開始します。 キャッシュの削除プロセスでは、キャッシュのスラッシングが発生する可能性があります。キャッシュは頻繁に作成および削除されます。 これを減らすために、リポジトリのキャッシュを確認し、特定のワークフローからキャッシュを削除したり キャッシュ サイズを大きくしたりするなどの修正手順を実行できます。 この機能は、支払い方法が登録されており、キャッシュ設定を構成してオプトインしたユーザーのみが利用できます。 [「AUTOTITLE」を](/ja/actions/how-tos/managing-workflow-runs-and-deployments/managing-workflow-runs/manage-caches)参照してください。 キャッシュ エントリは、リポジトリごとに 1 分あたり最大 200 アップロードの割合で作成し、リポジトリごとに 1 分あたり 1500 ダウンロードの速度でダウンロードできます。 このレートを超えると、関連するレート制限がリセットされるまで、後続のキャッシュのアップロードまたはダウンロードの試行は失敗します。 応答の `Retry-After` ヘッダーには、レート制限がリセットされるまでの時間が返されます。 [ ](/ja/actions/reference/limits)レート制限の詳細については、GitHub Actions を参照してください。 ### キャッシュ サイズの増加 キャッシュ エントリが削除される速度を下げる場合は、\[アクションの設定] でキャッシュのストレージ制限を増やすことができます。 ユーザーが所有するリポジトリは、リポジトリごとに最大 10 TB を構成できます。 組織が所有するリポジトリの場合、構成可能な上限は組織の設定によって決まります。 企業が所有する組織の場合、構成可能な上限は企業の設定によって決まります。 既定の 10 GB を超えて制限を増やすと、そのストレージが使用されている場合、追加のコストが発生します。 詳細については、以下を参照してください。 * [リポジトリのGitHub Actions設定の管理](/ja/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-cache-settings-for-your-repository) * [組織のGitHub Actionsの無効化または制限](/ja/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-cache-storage-for-your-organization) * [企業でGitHub Actionsのポリシーを適用する](/ja/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#artifact-and-log-retention) 追加ストレージの使用は、 GitHub Actions または Actions Cache Storage SKU に設定された予算によっても制御されます。 制限が構成されていて、予算を超えた場合、キャッシュは課金状態が解決されるまで読み取り専用になります。または、キャッシュの有効期限が切れるか明示的に削除されることで、使用量が 10 GB の空き制限の下に入ります。 予算の設定方法の詳細については、 [従量制課金製品の支出を管理するための予算を設定する](/ja/billing/how-tos/set-up-budgets) を参照してください。 Actions Cache Storage SKU の予算を、課金期間中に構成されたストレージを使用する合計コストよりも低く設定すると、キャッシュが頻繁に読み取り専用モードになる可能性があります。 たとえば、SKU の予算が $0 で、リポジトリの最大キャッシュ サイズを 20 GB に構成した場合、ストレージが空きしきい値を超えるとすぐに、キャッシュは読み取り専用モードになります。 以下は、アクション キャッシュ ストレージ SKU に設定する予算を決定するための、いくつかの参考となる月額コストです。 | キャッシュ サイズ | 月額料金 (完全に利用されている場合) | | --------- | ------------------- | | 50GB | $2.80 | | 200 GB | $13.30 | | 1000 GB | $69.30 | ## 次のステップ 依存関係キャッシュの管理については、[「AUTOTITLE」](/ja/actions/how-tos/managing-workflow-runs-and-deployments/managing-workflow-runs/manage-caches)を参照してください。