GitHub Actions Caching: What to Cache and What Not To

Why caching in CI is different from caching in production

CI caches exist to avoid re-downloading packages that haven't changed. The cache must be invalidated when dependencies change (new package added, version bumped) and reused when they haven't.

The two failure modes:

1. No invalidation: cache stores stale packages → builds fail with wrong dependencies.
2. Over-invalidation: cache key changes on every run → no hits → slow builds.

The cache key is the mechanism that controls this. Get it wrong in either direction and the cache either corrupts your build or provides no benefit.

Node.js: cache the npm registry, not node_modules

npm ci deletes node_modules at the start of every run. Caching node_modules is therefore pointless — the first thing npm ci does is delete it.

The right approach: cache ~/.npm (the npm package registry cache). When npm ci runs, it downloads packages from the registry cache on disk rather than from the internet.

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

- name: Install dependencies
  run: npm ci

Key breakdown:

• npm-${{ runner.os }}-: prefix ensures cross-OS isolation.
• ${{ hashFiles('**/package-lock.json') }}: exact hash of the lockfile. Any package change produces a new hash → cache miss → fresh download. Same lockfile → cache hit → fast install.

The restore-keys fallback (npm-${{ runner.os }}-) matches any cache for this OS. If the lockfile changed, npm only downloads the new/changed packages — much faster than downloading everything fresh.

Simpler alternative: actions/setup-node has built-in caching:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # handles the above automatically

This is equivalent but requires less boilerplate.

Go modules

- name: Cache Go modules
  uses: actions/cache@v4
  with:
    path: |
      ~/go/pkg/mod
      ~/.cache/go-build
    key: go-${{ runner.os }}-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      go-${{ runner.os }}-

Two directories to cache:

• ~/go/pkg/mod: downloaded module source. Changes when go.sum changes.
• ~/.cache/go-build: compiled artifacts. Speeds up compilation, not just downloads.

The build cache (go-build) does not change when modules change — it changes when your source code changes. For most repos, the module download savings are most significant; the build cache savings are harder to predict because any code change invalidates it.

Python (pip)

- name: Cache pip
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ runner.os }}-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: |
      pip-${{ runner.os }}-

- run: pip install -r requirements.txt

For poetry, use poetry.lock as the hash source and cache the virtualenv:

- name: Cache poetry virtualenv
  uses: actions/cache@v4
  with:
    path: ~/.cache/pypoetry/virtualenvs
    key: poetry-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}

- name: Build and push
  uses: docker/build-push-action@v5
  with:
    cache-from: type=registry,ref=ghcr.io/myorg/myapp:cache
    cache-to: type=registry,ref=ghcr.io/myorg/myapp:cache,mode=max
    push: true
    tags: ghcr.io/myorg/myapp:latest

- name: Build
  uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max