actions/cache: Save & Restore Build Caches

actions/cache stores and restores files across runs, keyed by a hash you control.

Cache the expensive, rarely-changing work and key it so the cache changes exactly when its contents should. restore-keys give you prefix fallbacks on a near miss.

Key inputs (with:)

path: file or directory globs to cache (required).
key: the exact cache key, usually a lockfile hash.
restore-keys: ordered prefix fallbacks for partial restores.
enableCrossOsArchive: share caches across operating systems.
fail-on-cache-miss: error instead of continuing on a miss.

Example workflow

.github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-
      - run: npm ci

On any runner

actions/cache works on any runner. Latchkey managed runners run it unchanged, and add a transparent dependency cache that needs no key wrangling.

Key takeaways

key is an exact match; restore-keys are prefix fallbacks.
Key on a lockfile hash so the cache invalidates with content.
Many setup-* actions wrap cache for you behind cache: <pm>.