Caching dependencies to Speed up your workflow To make your workflow faster and more efficient, you can create and use caches for dependencies and other frequently reused files.

About caching workflow dependencies

Workflow runs typically reuse the same output or downloaded dependencies between runs. For example, software packages and dependency management tools such as Maven, Gradle, NPM, and Yarn keep local caches for downloaded dependencies.

GitHub hosted runners start in a clean virtual environment and must download dependencies each time, resulting in increased network utilization, increased uptime, and increased costs. To help speed up the re-creation of these files, GitHub can cache dependencies that you often use in your workflow.

To cache the dependencies of a job, you need to use GitHub’s cache operation. This operation retrieves a cache identified by a unique key. See Actions/Cache for more information.

Warning: It is recommended not to store any sensitive information in the public warehouse cache. For example, sensitive information can include access tokens or login credentials stored in files in the cache path. In addition, command-line interface (CLI) programs, such as Docker Login, can store access credentials in configuration files. Anyone with read access can create pull requests on the repository and access the cached content. A copy of the repository can also create pull requests on the base branch and access the cache on the base branch.

Compare component and dependency caches

Artifacts are similar to caches in that they can store files on GitHub, but each feature provides a different use case and cannot be used interchangeably.

If you want to reuse files that change infrequently between job or workflow runs, use caching. Use artifacts if you want to save the files generated by the job for viewing after the workflow ends. See “Persisting workflows with Artifacts” for more information.

Limits on access to the cache

Using v2 for cache operations, you can access the cache in the workflow triggered by any event with GITHUB_REF. If v1 of the cache operation is used, you can only access caches in the workflow triggered by push and pull_REQUEST events, except for pull_REQUEST closed events. See “Events that Trigger workflow” for more information.

The workflow can access and restore caches created in the current branch, the base branch (including the base branch of the replicated repository), or the default branch (usually Master). For example, caches created on the default branch master can be accessed from any pull request. In addition, if branch feature-b has the base branch feature-a, the workflow triggered by feature-b can access the caches created in the default branch (master), feature-a, and feature-b.

Access restrictions provide cache isolation and security by creating logical boundaries between different workflows and branches. For example, a cache created for branch feature-a (with base branch master) will not be able to access pull requests from branch feature-b (with base branch Master).

Cache operation

The cache operation attempts to recover the cache based on the key you provided. When the operation finds the cache, it restores the cached file to the path you configured.

If there is no exact match, the operation creates a new cache entry when the job completes successfully. The new cache will use the key you provided and contain the files in the PATH directory.

You can optionally provide a list of restorest-keys to use when the key does not match the existing cache. The restore-keys list is useful because restore-keys can partially match cached keys. For more information on matching restorest-keys, see “Matching Cache Keys.”

See Actions/Cache for more information.

Input parameters for cache operations

Key: The key created when it is necessary to save the cache, and the key used to search the cache. It can be any combination of variables, context values, static strings, and functions. The key contains a maximum of 512 characters. If the key length exceeds the maximum length, the operation will fail. Path: the path to cached or restored files on the required runner. The path can be absolute or relative to the working directory. With cache operated V2, you can specify a single path or multiple paths as lists. The path can be a directory or a single file and supports the Glob mode. For cache v1, only a single path is supported, which must be a directory. You cannot cache individual files. Restore-keys: Sequential list of other keys used to look up the cache if no cache hit has occurred for the optional key.

Output parameters of the cache operation

Cache-hit: Indicates the Boolean value that finds the exact match of the key.

Example of cache operation

This example creates a new cache when the package in the package-lock.json file changes, or when the operating system of the runner changes. The cache key uses context and expression to generate a key value that includes the operating system of the runner and the 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@v2

    - name: Cache node modules
      uses: actions/cache@v2
      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 }}-

    - name: Install Dependencies
      run: npm install

    - name: Build
      run: npm build

    - name: Test
      run: npm test
Copy the code

When the key matches an existing cache, it is said to be a cache hit, and the operation restores the cached files to the PATH directory.

When the key does not match the existing cache, it is said to be a cache miss, and a new cache is created when the job completes successfully. When a cache miss occurs, the operation searches for alternative key values called restorest-keys.

If you provide restored-keys, the cache operation searches in order for any caches that match the restored-keys list. When an exact match occurs, the operation restores the files in the cache to the PATH directory. If there is no exact match, the operation searches for a partial match of the recovery key value. When the operation finds a partial match, the most recent cache is restored to the PATH directory. The cache operation completes and the next workflow step in the job runs. If the job completes successfully, the action creates a new cache containing the contents of the PATH directory. To cache files in multiple directories, you need a step that uses the cache operation for each directory. After you create a cache, you cannot change the contents of an existing cache, but you can create a new cache with a new key.

Create a cache key using the context

The cache key can include any context, function, text, and operator supported by GitHub operations. See “Context and Expression Syntax for GitHub Operations” for more information.

Using expressions to create keys allows you to automatically create new caches when dependencies change. For example, you can create a key using an expression that evaluates the hash of an NPM package-lock.json file.

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

GitHub evaluates the expression hash “package-lock.json” to derive the final key.

npm-d5ea0750
Copy the code

Match cache key

The cache operation first searches for cache hits for keys and restored-keys in the branch that contains the workflow run. If there is no hit in the current branch, the cache operation searches for the key and restorest-keys in the parent and upstream branches.

You can provide a list of recovery keys to use in the event of a key cache miss. You can create multiple recovery keys from the most specific to the least specific. The cache operation searches the restorest-keys in sequence. When keys do not match directly, the operation searches for keys prefixed with the recovery key. If the recovery key value has more than one partial match, the operation returns the recently created cache.

An example of using multiple recovery key values

restore-keys: |
  npm-foobar-${{ hashFiles('package-lock.json') }}
  npm-foobar-
  npm-
Copy the code

The runner parses the evaluation expression into the following restorest-keys:

restore-keys: |
  npm-foobar-d5ea0750
  npm-foobar-
  npm-
Copy the code

Restore the key value npm-foobar- to match any key value beginning with the string npm-foobar-. For example, the key values npm-foobar-fd3052DE and npm-foobar-a9b253ff both match the recovery key value. The cache with the latest creation date will be used. The key values in this example are searched in the following order:

Npm-foobar-d5ea0750 matches the specific hash. Npm-foobar – matches the cache key value prefixed with npm-foobar-. NPM – matches any key value prefixed with NPM -.

Search priority example

  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-
Copy the code

For example, if the pull request contains the feature branch (current scope) and is directed against the default branch (master), the operation searches for key and restorest-keys in the following order:

Key values in the feature branch range npm-feature-d5eA0750 Key values in the feature branch range nPm-feature-key values in the feature branch range nPm-master key values in the feature branch range Npm-feature-d5ea0750 Key values in the master branch npm-d5eA0750 Key values in the master branch NPM

Use restriction and recall policy

GitHub will delete any cached entries that have not been accessed for 7 days. There is no limit to the number of caches that can be stored, but the total size of all caches in the repository is limited to 5 GB. If this limit is exceeded, GitHub will save the cache, but will start withdrawing it until the total size is less than 5 GB.