Sharing a mistake so it is one fewer for you.
Our pipeline cached dependencies to speed up builds. I set the cache key to the branch name, thinking "each branch gets its own cache". Looked clever. For two weeks nobody noticed that after a dependency update the CI kept building with the old versions. Tests passed in CI, failed on laptops. The classic "works on CI" bug, in reverse.
The fix is to key the cache on the content of the files that determine the dependencies:
- uses: actions/cache@v4
with:
path: ~/.cache/pip
key: pip-${{ runner.os }}-${{ hashFiles('requirements.lock') }}
restore-keys: |
pip-${{ runner.os }}-
When requirements.lock changes, the hash changes and the cache is rebuilt. restore-keys is a fallback prefix that restores the most recent partial cache as a starting point, so even a miss is faster than nothing.
Rules I wrote on the wall:
- A cache key must include every input that should invalidate it (lockfile, OS, tool version).
- A cache is an optimisation. A build with an empty cache must give the same result. Run one clean build on a schedule to check.
- Never cache things that hold secrets or build outputs you ship.
Also, yes, I wrote it, I merged it, and I approved my own change.