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.

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.

Package managers	setup-* action for caching
npm, Yarn, pnpm	setup-node
pip, pipenv, Poetry	setup-python
Gradle, Maven	setup-java
RubyGems	setup-ruby
Go go.sum	setup-go

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 "Storing workflow data as artifacts."

Restrictions for accessing a cache

Access restrictions provide cache isolation and security by creating a logical boundary between different branches or tags. Workflow runs can restore caches created in either the current branch or the default branch (usually main). If a workflow run is triggered for a pull request, it can also restore caches created in the base branch, including base branches of forked repositories. For example, if the branch feature-b has the base branch feature-a, a workflow run triggered on a pull request would have access to caches created in the default main branch, the base feature-a branch, and the current feature-b branch.

Workflow runs cannot restore caches created for child branches or sibling branches. For example, a cache created for the child feature-b branch would not be accessible to a workflow run triggered on the parent main branch. Similarly, a cache created for the feature-a branch with the base main would not be accessible to its sibling feature-c branch with the base main. Workflow runs also cannot restore caches created for different tag names. For example, a cache created for the tag release-a with the base main would not be accessible to a workflow run triggered for the tag release-b with the base main.

When a cache is created by a workflow run triggered on a pull request, the cache is created for the merge ref (refs/pull/.../merge). Because of this, the cache will have a limited scope and can only be restored by re-runs of the pull request. It cannot be restored by the base branch or other pull requests targeting that base branch.

Multiple workflow runs in a repository can share caches. A cache created for a branch in a workflow run can be accessed and restored from another workflow run 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 that exactly matches the key, the action restores the cached files to the path you configure. You can optionally provide a list of restore-keys to use in case 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."

If there is an exact match to the provided key, this is considered a cache hit. If no cache exactly matches the provided key, this is considered a cache miss. On a cache miss, 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. For more information about how this is handled, see "Cache hits and misses."

You cannot change the contents of an existing cache. Instead, you can create a new cache with a new 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-
  

• enableCrossOsArchive: Optional A boolean value that when enabled, allows Windows runners to save or restore caches independent of the operating system the cache was created on. If this parameter is not set, it defaults to false. For more information, see Cross OS cache in the Actions Cache documentation.

Output parameters for the cache action

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

Cache hits and misses

When key exactly 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 "