actions/cache

Cache any files between workflow runs, keyed on a hash of your lockfiles.

Official actionCategory: CachingLatest v4View on GitHub

What it does

actions/cache saves a set of paths after a job and restores them on later runs when the key matches, which is the main lever for cutting CI time.

A good key hashes your lockfiles so the cache invalidates when dependencies change; restore-keys provides a fallback to a recent partial cache.

Usage

workflow (.yml)

steps:
  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-

Inputs

Input	Description	Default	Required
`path`	File paths or globs to cache.	-	Yes
`key`	Exact cache key, usually including a lockfile hash.	-	Yes
`restore-keys`	Ordered prefixes to fall back to on a key miss.	-	No
`fail-on-cache-miss`	Fail the step if no cache is found.	`false`	No
`lookup-only`	Check for a cache without downloading it.	`false`	No

Outputs

Output	Description
`cache-hit`	true only on an exact key match (not a restore-keys match).

Notes

Total cache storage is limited to 10 GB per repository; least-recently-used entries are evicted. Caches untouched for 7 days are removed.

A cache written on a branch is restorable on that branch and on its base branch, not across unrelated branches.

Common errors

A cache that never restores usually has a key that changes every run (for example it includes github.sha). Key on lockfile hashes instead.
A stale cache that never updates means the key never changes. Include hashFiles(...) of your lockfile so it rotates.

Security and pinning

Do not cache secrets or credentials. Cache contents are readable by any workflow run on the repository.

Alternatives and related

actions/setup-nodeInstall a specific Node.js version and cache your npm, yarn, or pnpm dependencies. actions/setup-pythonInstall a specific Python version and cache pip, pipenv, or poetry dependencies.

Frequently asked questions

When should I use actions/cache vs the setup-* cache input?

Prefer the setup action cache input for language dependencies. Use actions/cache for anything else: build output, compiled artifacts, tool downloads.

Why is cache-hit false even though it restored something?

cache-hit is only true on an exact key match. A restore-keys fallback restores files but reports cache-hit as false.

References

GitHub Actions documentation