Cache keys that survive monorepo refactors
Why hashing package lockfiles alone is not enough when folders move and toolchains bump mid-sprint.
Monorepos rearrange directories often. Cache keys tied only to a lockfile restore the wrong tree when a package moves, then force a full rebuild that looks like a mysterious regression.
We prefer composite keys: toolchain version, lockfile hash, and a content hash of the package's own sources plus its declared workspace dependencies. Moves that do not change content keep the hit; moves that do invalidate correctly.
Runner placement matters too. Shared caches across incompatible OS images look fast until binary artifacts poison a Linux job with a macOS path. Separate cache namespaces by OS and architecture.
Document the key recipe in the golden pipeline template so new services inherit the same rules instead of inventing one-off hashes that expire after the next refactor.