GitHub Actions Cache Keys: Stop Wasting 3 Minutes Every Run
Getting Composer and npm caching right in GitHub Actions is not hard, but the wrong cache key will silently cost you on every single run.
I've watched the same cache misconfiguration waste three minutes per run across a half-dozen client projects. It's not obvious until you notice your CI times are identical whether the cache hit or not. Here's what goes wrong and how to actually fix it.
What GitHub Actions Cache Is Actually Doing
The actions/cache step stores a directory on GitHub's infrastructure, keyed by a string you define. On the next run, if the key matches exactly, the directory is restored before your steps execute. If it doesn't match, you get nothing - a cache miss - and you install everything from scratch.
That's the whole thing. The power is in the key. And the key is where everyone screws it up.
The Mistake: Hashing the Wrong File
Here's the pattern I see copied from blog posts and the GitHub docs examples:
- uses: actions/cache@v4
with:
path: vendor
key: composer-${{ hashFiles('composer.lock') }}
That looks right. It even works, mostly. The problem is what happens when you have a monorepo structure, or when you've got a composer.lock that gets regenerated by a pre-step, or - the case that burned me on a healthcare dashboard project last year - when your workflow checks out a branch where composer.lock is identical to main but composer.json has changed in a way that hasn't been locked yet.
But the bigger, more common mistake is this one:
key: composer-${{ runner.os }}-${{ github.sha }}
I've seen this in real repos. github.sha is the commit hash. It's unique per commit. Your cache will never, ever hit because the key changes on every single push. You are paying the full install cost every run while also storing a new cache artifact every run. GitHub eventually evicts old caches after 7 days of no access, so you're just burning storage and time.
The Right Keys for Composer and npm
Here's what I actually ship in NWOS client projects:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
extensions: mbstring, pdo_mysql, redis
coverage: none
- name: Cache Composer dependencies
id: composer-cache
uses: actions/cache@v4
with:
path: vendor
key: composer-${{ runner.os }}-${{ hashFiles('**/composer.lock') }}
restore-keys: |
composer-${{ runner.os }}-
- name: Install Composer dependencies
if: steps.composer-cache.outputs.cache-hit != 'true'
run: composer install --no-interaction --prefer-dist --optimize-autoloader
- name: Cache npm dependencies
id: npm-cache
uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-
- name: Install npm dependencies
run: npm ci
- name: Build assets
run: npm run build
A few things worth calling out here.
hashFiles('**/composer.lock') vs hashFiles('composer.lock')
The double-star glob finds composer.lock anywhere in the repo. For a standard Laravel app these are equivalent. For anything with nested packages or a packages/ directory, the glob version catches changes you'd otherwise miss. I use it by default now.
runner.os in the key
If you ever run the same workflow on multiple OS targets (ubuntu + windows for some reason, or if a client adds a macOS runner), you don't want a Linux vendor directory being restored on Windows. Including runner.os prevents that. It's a free safeguard.
restore-keys
This is the partial match fallback. If the exact key misses - say you just updated one package and composer.lock changed - GitHub will fall back to any cache that starts with composer-ubuntu-latest-. You get a stale vendor directory, then composer install runs and updates only what changed. That's significantly faster than a cold install.
The if: steps.composer-cache.outputs.cache-hit != 'true' condition
This is optional but I like it. When you get a perfect cache hit, you skip the install step entirely. Zero network calls to packagist, zero disk writes. On a warm cache hit for a medium-sized Laravel app that's about 90 seconds saved.
Note that for npm ci I don't add that condition. npm ci with a primed ~/.npm cache is already fast because the tarballs are local. The network is the slow part, not the install. So I let it run and it typically finishes in 10-15 seconds even on cache hit.
Caching the Right Path for npm
This tripped me up early on. There are two reasonable things to cache for npm:
~/.npm- the global npm cache directory (tarballs)node_modules- the installed tree
Caching node_modules directly sounds appealing but it's fragile. Node modules contain platform-specific binaries. If your runner image updates, you can end up with a restored node_modules that has broken native modules and a CI job that fails in confusing ways. I've been there with a Vite build that started segfaulting after an Ubuntu runner update.
Cache ~/.npm instead. Let npm ci do the actual install from the local tarball cache. It's slightly slower than restoring node_modules directly but it's reliable.
For Composer, caching vendor directly is fine because PHP packages are platform-agnostic (assuming you're not using native extensions installed via composer). I haven't had issues with this approach across dozens of Laravel projects.
The Gotcha Nobody Mentions: Cache Poisoning on PRs
If you allow external contributors to open PRs against your repo, be careful. By default, workflows triggered by pull_request events from forks can write to the cache. GitHub addressed this somewhat - fork PRs from external contributors run with read-only cache access since 2023 - but if you're on a public repo with internal contributors who push branches, everyone shares the same cache namespace.
This means a branch that installs a sketchy or broken package version can pollute the cache for other branches, until the cache expires or you manually clear it via the GitHub UI (or the API).
For internal teams on private repos, this hasn't bitten me. For open source projects or anything with external contributors, I'd think harder about it.
Invalidating the Cache When You Need To
Sometimes you need a clean slate - a package published a bad version, your vendor directory got corrupted, whatever. You can't just change composer.lock to bust the key without an actual dependency change.
The easiest pattern is to add a manual bust variable to your key:
key: composer-v2-${{ runner.os }}-${{ hashFiles('**/composer.lock') }}
When you need to force a fresh cache, bump v2 to v3 in the workflow file, commit it, and your next run starts cold. Every run after that re-warms the cache normally. I keep this prefix in all my workflow files now as a standard escape hatch.
You can also clear specific cache entries through the GitHub UI under Actions > Caches, or via the REST API if you want to automate it. But the version prefix is simpler for one-off situations.
When This Matters Most
For a small app with 30 Composer packages and minimal npm dependencies, getting this wrong costs maybe 90 seconds per run. Annoying but not catastrophic.
For a larger Laravel app - I'm thinking of an e-commerce client project with 120+ Composer packages, a full Tailwind/Vite build pipeline, and PHPUnit running against a MySQL service container - a cold install plus asset build is 4.5 to 5 minutes. A warm cache hit with everything configured correctly gets that down to under 90 seconds. That's the difference between CI being part of your flow and CI being something you check on after getting coffee.
If you're paying for GitHub Actions minutes on a private repo, it's also real money. At current rates, shaving 3 minutes off 50 runs a month is 150 minutes. Not retirement money, but it adds up across multiple clients.
When I'd Skip the Cache Step
For dead-simple projects - a WordPress site with one custom plugin, a static site generator with 10 npm packages - the cache setup adds complexity that doesn't pay off. If your full install takes 45 seconds, the YAML overhead and occasional cache miss debugging isn't worth it.
I also skip it on matrix builds where I'm testing against multiple PHP versions and the job count is already high. The cache interaction across matrix axes gets fiddly and I'd rather have predictable cold installs than chase down why PHP 8.1 is hitting a stale PHP 8.3 cache.
For everything else - any app that runs in production with real traffic, any project with active development - set this up once and forget about it.
Get the key right the first time and CI caching just works. Get it wrong and you'll spend weeks wondering why your builds never seem to get faster. The hash of your lockfile is the key. Everything else is decoration.
Need help shipping something like this? Get in touch.