Caching dependencies to speed up workflows

About caching workflow dependencies

Workflow runs often reuse the same outputs or downloaded dependencies from one run to another. For example, package and dependency management tools such as Maven, Gradle, npm, and Yarn keep a local cache of downloaded dependencies.

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.

Comparing artifacts and dependency caching

Artifacts and caching are similar because they provide the ability to store files on GitHub, but each feature offers different use cases and cannot be used interchangeably.

• 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."

Restrictions for accessing a cache

A workflow can access and restore a cache created in the current branch, the base branch (including base branches of forked repositories), or the default branch (usually main). For example, a cache created on the default branch would be accessible from any pull request. Also, if the branch feature-b has the base branch feature-a, a workflow triggered on feature-b would have access to caches created in the default branch (main), feature-a, and 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.

Using the cache action

The cache action will attempt to restore a cache based on the key you provide. When the action finds a cache, the action restores the cached files to the path you configure.

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.

You can optionally provide a list of restore-keys to use when the key doesn't match an existing cache. A list of restore-keys is useful when you are restoring a cache from another branch because restore-keys can partially match cache keys. For more information about matching restore-keys, see "Matching a cache key."

Input parameters for the cache action

• key: Required The key created when saving a cache and the key used to search for a cache. It can be any combination of variables, context values, static strings, and functions. Keys have a maximum length of 512 characters, and keys longer than the maximum length will cause the action to fail.

• 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. For example:

    - 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. For example:

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

Output parameters for the cache action

• cache-hit: A boolean value to indicate an exact match was found for the key.

Example using the cache action

This example creates a new cache when the packages in package-lock.json file change, or when the runner's operating system changes. The cache key uses contexts and expressions to generate a key that includes the runner's operating system and a SHA-256 hash of the package-lock.json file.

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. If you provide restore-keys, the cache action sequentially searches for any caches that match the list of restore-keys.
   • When there is an exact match, the action restores the files in the cache to the path directory.
   • If there are no exact matches, the action searches for partial matches of the restore keys. When the action finds a partial match, the most recent cache is restored to the path directory.
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." Once you create a cache, you cannot change the contents of an existing cache but you can create a new cache with a new key.

Using contexts to create cache keys

A cache key can include any of the contexts, functions, literals, and operators supported by 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.

For example, you can create a key using an expression that calculates the hash of an npm package-lock.json file. 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 evaluates the expression hash "package-lock.json" to derive the final 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

Matching a cache key

The cache action first searches for cache hits for key and restore-keys in the branch containing the workflow run. If there are no hits in the current branch, the cache action searches for key and restore-keys in the parent branch and upstream branches.

restore-keys allows you to specify a list of alternate restore keys to use when there is a cache miss on key. You can create multiple restore keys ordered from the most specific to least specific. The cache action searches the restore-keys in sequential order. When a key doesn't match directly, the action searches for keys prefixed with the restore key. If there are multiple partial matches for a restore key, the action returns the most recently created cache.

Example using multiple restore keys

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

The runner evaluates the expressions, which resolve to these 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. The cache with the most recent creation date would be used. The keys in this example are searched in the following order:

1. npm-feature-d5ea0750 matches a specific hash.
2. npm-feature- matches cache keys prefixed with npm-feature-.
3. npm- matches any keys prefixed with npm-.

Example of search priority

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

Usage limits and eviction policy

GitHub will remove any cache entries that have not been accessed in over 7 days. 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. You can use the API to list and delete cache entries, and see your cache usage. For more information, see the "GitHub Actions Cache" REST API documentation.

You can also install a GitHub CLI extension to manage your caches from the command line. For more information about the extension, see the extension documentation. For more information about GitHub CLI extensions, see "Using GitHub CLI extensions."