依存関係キャッシュのリファレンス

`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: Optional 有効にすると、キャッシュが作成されたオペレーティングシステムとは別に、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 ハッシュを含むキーを生成します。

YAML

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

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でサポートされているコンテキスト、関数、リテラル、および演算子のいずれかを含めることができます。詳細については、「コンテキストリファレンス」および「ワークフロー内とアクション内で式を評価する」を参照してください。

式を使用して key を作成すると、依存関係が変更されたときに新しいキャッシュを自動的に作成できます。

たとえば、npm key ファイルのハッシュを計算する式を使用して package-lock.json を作成できます。その場合、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 と_バージョン_を検索します。それでも現在のブランチでヒットが見つからない場合、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 を次の順序で検索します。

npm-feature-d5ea0750 ブランチ内のキー feature
npm-feature- ブランチ内のキー feature
npm- ブランチ内のキー feature
npm-feature-d5ea0750 ブランチ内のキー main
npm-feature- ブランチ内のキー main
npm- ブランチ内のキー main

特定のパッケージマネージャ向け `setup-*` アクション

以下に示すパッケージマネージャーをキャッシュする場合、それぞれの setup-* アクションを使用するには、最小構成が必要となります。これにより、依存関係キャッシュが作成され、復元されます。

パッケージマネージャー	キャッシュの setup-* アクション
npm、Yarn、pnpm
setup-node
pip、pipenv、Poetry
setup-python
Gradle、Maven
setup-java
RubyGems
setup-ruby
開始 `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 でトリガーされたワークフロー実行からアクセスすることはできません。同様に、ベース 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) のスコープであり、既定のブランチのスコープに書き込むことはできません。詳細については、「キャッシュにアクセスする際の制限」を参照してください。

読み取り専用キャッシュアクセスを使用した実行でキャッシュを保存しようとすると、保存は失敗しますが、ステップとジョブは保存されません。ワークフローは続行され、エラーはワークフローログに警告として報告されます。その場合は、次の点を考慮してください。

既定のブランチスコープでキャッシュのパフォーマンス上の利点を維持するには、キャッシュを更新し続ける信頼されたワークフロー (たとえば、既定のブランチに対する push によってトリガーされる CI ビルド) があることを確認します。これらのキャッシュエントリは、 pull_request_targetなどの低信頼イベントによってトリガーされるワークフローによって復元できます。
信頼度の低いワークフローでは、 actions/cache/restore などの復元専用のキャッシュ操作に切り替えて、目的のキャッシュの使用状況を明確にし、ワークフロー実行ログの警告を回避します。

キャッシュを安全に使用するためのベストプラクティス

キャッシュの内容は署名も検証もされず、キャッシュを読み取ることができるワークフロー実行では、その内容が抽出される可能性があります。抽出されたキャッシュは、その後ワークフロー実行で実行されるファイルを変更し、悪意のあるコードが実行される可能性があります。キャッシュを使用する場合のセキュリティリスクを軽減するには、次のプラクティスに従います。

機密情報をキャッシュに格納しないでください。 リポジトリに対して pull request を開くことができるすべてのユーザーは、ベースブランチ内のキャッシュの内容を読み取ることができます。キャッシュされたパスにシークレット、トークン、または資格情報を書き込むことはありません。代わりに機密値をシークレットとして格納します。「シークレット」を参照してください。
信頼されたトリガーからキャッシュを保存します。 信頼されたアクター (通常はリポジトリへの書き込みアクセス権を持つもの) によってトリガーされるワークフローへのキャッシュ書き込みを制限します。キャッシュに書き込むことができるワークフロートリガーを制限するために適用される既定の制限については、低信頼ワークフロートリガーのキャッシュアクセスを参照してください。さらに、デプロイ保護規則がある環境を使用して、キャッシュを変更できるワークフローをさらに制限することを検討してください。「デプロイメント用の環境管理」を参照してください。
ワークフローのベストセキュリティプラクティスに従って、ワークフローを強化します。 キャッシュ/書き込みアクセス権を持つワークフローを、ワークフローの脆弱性に対して強化されたワークフローに制限します。セキュリティで保護された使用に関するリファレンスのガイダンスに従って、コードの実行や悪意のあるキャッシュエントリの導入につながる可能性のあるワークフローの脆弱性を防ぎます。

ワークフローのセキュリティ保護に関するより広範なガイダンスについては、セキュリティで保護された使用に関するリファレンスを参照してください。

利用制限と退去のポリシー

GitHub は、キャッシュストレージとリテンション期間に制限を適用してストレージコストを管理し、不正使用を防ぎます。これらの制限を理解することは、キャッシュの使用を最適化するのに役立ちます。

既定の制限

GitHub では、7 日間にわたってアクセスされていないキャッシュエントリが削除されます。格納できるキャッシュの数に制限はありませんが、リポジトリ内のすべてのキャッシュの合計サイズは制限されています。既定では、この制限はリポジトリあたり 10 GB ですが、この制限はエンタープライズ所有者、組織の所有者、またはリポジトリ管理者が増やすことができます。 10 GB を超える使用量は、アカウントに課金されます。リポジトリが最大キャッシュストレージに達すると、キャッシュの削除ポリシーにより、最終アクセス日時が最も古いものから最も新しいものの順にキャッシュが削除されて、スペースが作成されます。

この制限を超えると、GitHub は新しいキャッシュを保存しますが、合計サイズがリポジトリの制限を下回るまでキャッシュの削除を開始します。キャッシュの削除プロセスでは、キャッシュのスラッシングが発生する可能性があります。キャッシュは頻繁に作成および削除されます。これを減らすために、リポジトリのキャッシュを確認し、特定のワークフローからキャッシュを削除したりキャッシュサイズを大きくしたりするなどの修正手順を実行できます。この機能は、支払い方法が登録されており、キャッシュ設定を構成してオプトインしたユーザーのみが利用できます。「AUTOTITLE」を参照してください。

キャッシュエントリは、リポジトリごとに 1 分あたり最大 200 アップロードの割合で作成し、リポジトリごとに 1 分あたり 1500 ダウンロードの速度でダウンロードできます。このレートを超えると、関連するレート制限がリセットされるまで、後続のキャッシュのアップロードまたはダウンロードの試行は失敗します。応答の Retry-After ヘッダーには、レート制限がリセットされるまでの時間が返されます。レート制限の詳細については、GitHub Actions を参照してください。

キャッシュサイズの増加

キャッシュエントリが削除される速度を下げる場合は、[アクションの設定] でキャッシュのストレージ制限を増やすことができます。ユーザーが所有するリポジトリは、リポジトリごとに最大 10 TB を構成できます。組織が所有するリポジトリの場合、構成可能な上限は組織の設定によって決まります。企業が所有する組織の場合、構成可能な上限は企業の設定によって決まります。既定の 10 GB を超えて制限を増やすと、そのストレージが使用されている場合、追加のコストが発生します。

詳細については、以下を参照してください。

追加ストレージの使用は、 GitHub Actions または Actions Cache Storage SKU に設定された予算によっても制御されます。制限が構成されていて、予算を超えた場合、キャッシュは課金状態が解決されるまで読み取り専用になります。または、キャッシュの有効期限が切れるか明示的に削除されることで、使用量が 10 GB の空き制限の下に入ります。予算の設定方法の詳細については、従量制課金製品の支出を管理するための予算を設定するを参照してください。

Actions Cache Storage SKU の予算を、課金期間中に構成されたストレージを使用する合計コストよりも低く設定すると、キャッシュが頻繁に読み取り専用モードになる可能性があります。たとえば、SKU の予算が $0 で、リポジトリの最大キャッシュサイズを 20 GB に構成した場合、ストレージが空きしきい値を超えるとすぐに、キャッシュは読み取り専用モードになります。

以下は、アクションキャッシュストレージ SKU に設定する予算を決定するための、いくつかの参考となる月額コストです。

キャッシュサイズ	月額料金 (完全に利用されている場合)
50GB	$2.80
200 GB	$13.30
1000 GB	$69.30

次のステップ

依存関係キャッシュの管理については、「AUTOTITLE」を参照してください。

依存関係キャッシュのリファレンス

この記事で