依存関係をキャッシュしてワークフローのスピードを上げる

ワークフローの依存関係のキャッシングについて

ワークフローの実行は、しばしば他の実行と同じ出力あるいはダウンロードされた依存関係を再利用します。 たとえばMaven、Gradle、npm、Yarnといったパッケージ及び依存関係管理ツールは、ダウンロードされた依存関係のローカルキャッシュを保持します。

Jobs on GitHub-hosted runners start in a clean virtual environment and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost. To help speed up the time it takes to recreate files like dependencies, GitHub can cache files you frequently use in workflows.

To cache dependencies for a job, you can use GitHub's cache action. The action creates and restores a cache identified by a unique key. Alternatively, if you are caching the package managers listed below, using their respective setup-* actions requires minimal configuration and will create and restore dependency caches for you.

成果物の比較と依存関係のキャッシング

成果物とキャッシングは、GitHubにファイルを保存できるようにするので似ていますが、それぞれの機能のユースケースは異なっており、入れ替えて使うことはできません。

• Use caching when you want to reuse files that don't change often between jobs or workflow runs, such as build dependencies from a package management system.
• Use artifacts when you want to save files produced by a job to view after a workflow run has ended, such as built binaries or build logs.

For more information on workflow run artifacts, see "Persisting workflow data using artifacts."

キャッシュへのアクセスについての制限

ワークフローは、現在のブランチ、ベースブランチ（フォークされたリポジトリのベースブランチを含む）、またはデフォルトブランチ（通常は main）で作成されたキャッシュにアクセスして復元できます。 たとえば、デフォルトブランチで作成されたキャッシュは、どのPull Requestからもアクセスできます。 また、feature-b ブランチに feature-a ベースブランチがある場合、feature-b でトリガーされたワークフローは、デフォルトのブランチ（main）、feature-a、および feature-b で作成されたキャッシュにアクセスできます。

Access restrictions provide cache isolation and security by creating a logical boundary between different branches. For example, a cache created for the branch feature-a (with the base main) would not be accessible to a pull request for the branch feature-c (with the base main).

Multiple workflows within a repository share cache entries. A cache created for a branch within a workflow can be accessed and restored from another workflow for the same repository and branch.

cacheアクションの利用

The cache action will attempt to restore a cache based on the key you provide. このアクションは、キャッシュを見つけるとそのキャッシュされたファイルを設定されたpathにリストアします。

If there is no exact match, the action automatically creates a new cache if the job completes successfully. The new cache will use the key you provided and contains the files you specify in path.

既存のキャッシュにkeyがマッチしなかった場合に使われる、restore-keysのリストを提供することもできます。 restore-keysのリストは、 restore-keysがキャッシュキーと部分的にマッチできるので、他のブランチからのキャッシュをリストアする場合に役立ちます。 restore-keysのマッチに関する詳しい情報については「キャッシュキーのマッチ」を参照してください。

cache アクションの入力パラメータ

• key: 必須 このキーはキャッシュの保存時に作成され、キャッシュの検索に使われます。 It can be any combination of variables, context values, static strings, and functions. キーの長さは最大で512文字であり、キーが最大長よりも長いとアクションは失敗します。

• path: Required The path(s) on the runner to cache or restore.

  • You can specify a single path, or you can add multiple paths on separate lines. 例:

    - name: Cache Gradle packages
      uses: actions/cache@v3
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
    

  • You can specify either directories or single files, and glob patterns are supported.

  • You can specify absolute paths, or paths relative to the workspace directory.

• restore-keys: Optional A string containing alternative restore keys, with each restore key placed on a new line. If no cache hit occurs for key, these restore keys are used sequentially in the order provided to find and restore a cache. 例:

  restore-keys: |
    npm-feature-${{ hashFiles('package-lock.json') }}
    npm-feature-
    npm-
  

cacheアクションの出力パラメータ

• cache-hit: キーの完全一致が見つかったことを示すブール値。

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@v3

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v3
        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 == false }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm build

      - name: Test
        run: npm test

When key matches an existing cache, it's called a cache hit, and the action restores the cached files to the path directory.

When key doesn't match an existing cache, it's called a cache miss, and a new cache is automatically created if the job completes successfully.

When a cache miss occurs, the action also searches your specified restore-keys for any matches:

1. restore-keysが渡された場合、cacheアクションはrestore-keysのリストにマッチするキャッシュを順番に検索します。
   • 完全なマッチがあった場合、アクションはそのファイルをpathディレクトリ中のキャッシュにリストアします。
   • 完全なマッチがなかった場合、アクションはリストアキーに対する部分一致を検索します。 アクションが部分一致を見つけた場合、最も最近のキャッシュがpathディレクトリにリストアされます。
2. The cache action completes and the next step in the job runs.
3. If the job completes successfully, the action automatically creates a new cache with the contents of the path directory.

For a more detailed explanation of the cache matching process, see "Matching a cache key." キャッシュをいったん作成すると、既存のキャッシュの内容を変更することはできませんが、新しいキーで新しいキャッシュを作成することはできます。

コンテキストを使ったキャッシュキーの作成

キャッシュキーには、コンテキスト、関数、リテラル、GitHub Actionsがサポートする演算子を含めることができます。 For more information, see "Contexts" and "Expressions."

Using expressions to create a key allows you to automatically create a new cache when dependencies change.

たとえばnpmのpackage-lock.jsonファイルのハッシュを計算する式を使ってkeyを作成できます。 So, when the dependencies that make up the package-lock.json file change, the cache key changes and a new cache is automatically created.

npm-${{ hashFiles('package-lock.json') }}

GitHubはhash "package-lock.json"という式を評価して、最終的なkeyを導出します。

npm-d5ea0750

Using the output of the cache action

You can use the output of the cache action to do something based on whether a cache hit or miss occurred. If there is a cache miss (an exact match for a cache was not found for the specified key), the cache-hit output is set to false.

In the example workflow above, there is a step that lists the state of the Node modules if a cache miss occurred:

- if: ${{ steps.cache-npm.outputs.cache-hit == false }}
  name: List the state of node modules
  continue-on-error: true
  run: npm list

キャッシュキーのマッチング

cache アクションは最初に、ワークフロー実行を含むブランチで key および restore-keys のキャッシュヒットを検索します。 現在のブランチにヒットがない場合、cache アクションは、親ブランチと上流のブランチで key および restore-keys を検索します。

restore-keys allows you to specify a list of alternate restore keys to use when there is a cache miss on key. 特定の度合いが強いものから弱いものへ並べて複数のリストアキーを作成できます。 The cache action searches the restore-keys in sequential order. キーが直接マッチしなかった場合、アクションはリストアキーでプレフィックスされたキーを検索します。 リストアキーに対して複数の部分一致があった場合、アクションは最も最近に作成されたキャッシュを返します。

複数のリストアキーの利用例

restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-

ランナーは式を評価します。この式は以下のようなrestore-keysになります。

restore-keys: |
  npm-feature-d5ea0750
  npm-feature-
  npm-

The restore key npm-feature- matches any key that starts with the string npm-feature-. For example, both of the keys npm-feature-fd3052de and npm-feature-a9b253ff match the restore key. 最も最近の期日に作成されたキャッシュが使われます。 この例でのキーは、以下の順序で検索されます。

1. npm-feature-d5ea0750 matches a specific hash.
2. npm-feature- matches cache keys prefixed with npm-feature-.
3. npm-はnpm-をプレフィックスとする任意のキーにマッチします。

検索の優先度の例

key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

For example, if a pull request contains a feature branch and targets the default branch (main), the action searches for key and restore-keys in the following order:

1. Key npm-feature-d5ea0750 in the feature branch
2. Key npm-feature- in the feature branch
3. Key npm- in the feature branch
4. Key npm-feature-d5ea0750 in the main branch
5. Key npm-feature- in the main branch
6. Key npm- in the main branch

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

GitHubは、7日間以上アクセスされていないキャッシュエントリを削除します。 There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited to 10 GB.

If you exceed the limit, GitHub will save the new cache but will begin evicting caches until the total size is less than the repository limit.

Managing caches

You can use the GitHub REST API to manage your caches. At present, you can use the API to see your cache usage, with more functionality expected in future updates. For more information, see the "Actions" REST API documentation.