GitHub Actions Cache Strategy: Speed Up CI/CD Pipeline 5x

npm install: 3 minutes and 15 seconds.

That was the CI build time for a project I inherited last year. Every time I pushed code, I’d stare at GitHub Actions logs, waiting for that green checkmark. Honestly, I spent a lot of that time doom-scrolling Twitter—what else could I do?

Then I added caching. Same build? 40 seconds. Nearly 5x faster.

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

This isn’t magic. It’s just getting GitHub Actions cache strategy right. Today, I’ll share the pitfalls I hit, the data I tested, and configuration templates you can copy-paste. If you’re waiting on CI builds, this might save you some coffee breaks.

1. Core Concepts of Cache Mechanism

Before configuring, let’s understand how caching works—otherwise you’ll trip over the same issues I did.

GitHub Actions caching is straightforward: find → restore → save. You define a key, GitHub searches all caches for a match. Found it? It restores directly to your workspace. Not found? After the job completes, it saves a new cache.

But there are hard limits you should know:

I’ve seen someone hit the 10GB wall—too many dependencies, caches piling up, then new caches get rejected, old ones get evicted, and every build is a “cold start.”

Another thing people confuse: Cache vs Artifact. Cache is for CI, optimized for speed. Artifacts are for humans—build outputs, test reports, things you want to keep long-term. Cache has a 10GB limit; Artifacts have no hard limit (but they eat into your repo storage).

There’s also Docker Layer Cache, specifically for Docker builds. The logic differs from regular caching—I’ll cover that separately.

2. Cache Key Design Strategy

Cache hit or miss entirely depends on your key design. This is the core of your caching strategy.

What is hashFiles()?

GitHub provides a built-in function hashFiles() that computes file hashes. Commonly used on package-lock.json or yarn.lock—if dependencies don’t change, the hash doesn’t change, and the cache hits.

key: npm-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

This generates a key like npm-Linux-a1b2c3d4e5f6.... As long as package-lock.json stays the same, the key stays the same.

restore-keys: The Fallback

But dependencies do update. That’s where restore-keys comes in—a “fallback matching” mechanism:

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

First, match the full key. No match? Fall back to old caches starting with npm-Linux-. Not a perfect hit, but at least most packages in node_modules are there—you only need to install the new dependencies incrementally.

Three Key Naming Patterns Compared

Based on my testing, here are three recommended patterns:

Simple Pattern (good for small projects):

key: {{ runner.os }}-node-{{ hashFiles('**/package-lock.json') }}

Version Pattern (for multiple Node versions):

key: {{ runner.os }}-node{{ matrix.node-version }}-{{ hashFiles('**/package-lock.json') }}

Multi-path Pattern (for monorepos):

key: {{ runner.os }}-{{ hashFiles('**/package-lock.json', '**/yarn.lock') }}

How to Check If Cache Hit

actions/cache outputs a cache-hit variable:

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

- uses: actions/cache@v4
  id: cache-npm
  with:
    path: ~/.npm
    key: {{ runner.os }}-node-{{ hashFiles('**/package-lock.json') }}

- name: Check cache hit
  run: echo "Cache hit - {{ steps.cache-npm.outputs.cache-hit }}"

true means exact hit; false means partial hit or complete miss. You can use this to decide whether to run npm ci:

- name: Install dependencies
  if: steps.cache-npm.outputs.cache-hit != 'true'
  run: npm ci

3. Practical Configuration Examples

Theory done. Let’s look at code. These configurations are tested and ready to copy-paste.

npm Caching (Prefer setup-node)

setup-node actually has built-in caching—it’s cleaner than manually using actions/cache:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # or 'yarn', 'pnpm'

One line. Done. But if you want to cache other directories (like node_modules), you’ll still need actions/cache:

- uses: actions/cache@v4
  with:
    path: node_modules
    key: {{ runner.os }}-nm-{{ hashFiles('**/package-lock.json') }}
    restore-keys: {{ runner.os }}-nm-

My recommendation: Use setup-node’s built-in cache unless you have special requirements.

yarn and pnpm

yarn’s cache directory differs from npm:

- uses: actions/cache@v4
  with:
    path: |
      ~/.yarn/cache
      ~/.yarn/install-state.gz
    key: yarn-{{ runner.os }}-{{ hashFiles('**/yarn.lock') }}

pnpm is special—it uses a global store:

- uses: pnpm/action-setup@v4
  with:
    version: 9

- uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: pnpm-{{ runner.os }}-{{ hashFiles('**/pnpm-lock.yaml') }}

Python/pip Caching

Python project cache paths:

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

Docker Layer Cache

Docker builds are the biggest time sink. The good news: BuildKit supports GitHub Actions cache backend:

- uses: docker/setup-buildx-action@v3

- uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    cache-from: type=gha
    cache-to: type=gha,mode=max

type=gha tells it to use GitHub Actions cache service for Docker layers. In my testing, a 5-minute image build dropped to about 1 minute.

Go Module Cache

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

Rust Cargo Cache

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-{{ runner.os }}-{{ hashFiles('**/Cargo.lock') }}

Rust compiles slowly—caching saves massive time. But watch out for target directory growing indefinitely—I recommend periodic cleanup.

4. Performance Optimization and Best Practices

Here’s what I’ve learned from testing and from hitting pitfalls—hopefully it saves you some headaches.

Performance Benchmarks

According to RunsOn’s test report (updated January 2026), with proper caching:

Cache hit rates land between 70-90%, depending on how well you design your key strategy.

Common Pitfalls

Don’t Cache node_modules Directly

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

I made this mistake at first. Big mistake.

# Don't do this
path: node_modules

node_modules is platform-specific—packages installed on Linux might have issues running on Windows. The right approach: cache the global cache directory (~/.npm), let npm ci assemble it.

Cross-OS Caching Needs GNU tar + zstd

Default tar formats differ on macOS and Windows, causing cache restore failures. Add this config:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}
    enableCrossOsArchive: true

Cache Pollution Issues

Sometimes your cache stores broken dependencies, causing builds to fail repeatedly. Solutions:

1. Manual deletion: Go to GitHub repo → Actions → Caches page, click delete
2. Force key update: Add a prefix or timestamp to the key to regenerate

key: npm-v2-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

Best Practices Checklist

Before you configure, check these points:

1. Prefer built-in caching in official actions (setup-node, setup-python)
2. Include hashFiles in your key, otherwise dependencies update but you keep using old cache
3. Add restore-keys—fallback matching can save you
4. Don’t cache node_modules, cache global directories
5. Periodically clean old caches to avoid hitting the 10GB limit

5. Common Questions Answered

Q1: Why is my cache hit rate so low?

The most common reason: key changes too frequently. Maybe you added a timestamp or branch name—every push generates a new key. Solution: only use runner.os and hashFiles, remove unnecessary variables.

Another reason: hashFiles matched files it shouldn’t. If you wrote hashFiles('**/*.json'), changing any config file invalidates the cache. Fix it to only match package-lock.json or yarn.lock.

Q2: What happens when cache exceeds 10GB?

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

10GB seems like a lot, but monorepos or Docker caches blow past it easily. Solutions:

1. Periodic cleanup: GitHub Actions → Caches, manually delete old ones
2. Split caches: use different keys for different dependencies, avoid one cache for everything
3. Use self-hosted runners: they don’t have the 10GB limit

Q3: Do self-hosted runners need special configuration?

No special config needed—the cache mechanism works the same. But self-hosted runners have an advantage: caches are stored locally, no network transfer latency, so restore is faster. The downside: caches don’t auto-clean—you’ll need to write a script for that.

Q4: How to force cache update?

Change the key. Add a version prefix:

key: npm-v3-{{ runner.os }}-{{ hashFiles('**/package-lock.json') }}

Or just delete the old cache and let the system regenerate.

Conclusion

All that said, it boils down to one thing: use caching right, CI gets 5x faster.

Let me do the math—assuming you save 2 minutes per build, 10 builds a day, that’s 600 minutes a month. Almost 10 hours. Enough time to write quite a few articles.

If you’re new to GitHub Actions, start with setup-node’s built-in cache—one line does the job. When you hit bottlenecks, come back and explore more complex key strategies and Docker Layer Cache.

By the way, this is the 3rd article in the GitHub Actions guide series. I’ve previously covered CI pipeline setup and deployment strategies—check out the archives if you’re interested.

Next time you push code, check your build time. See if you can go from 3 minutes to 40 seconds. Give it a try.

8 min read · Published on: Apr 7, 2026 · Modified on: Apr 8, 2026

Easton

Technology