Researched guidance: How should CI caches avoid restoring incompatible dependencies across runtime versions?

Summary

Prevent incompatible dependency reuse by separating download-store caches from installed or compiled artifacts. Key every environment-dependent cache with the lockfile plus all dimensions that change the cached bytes or their interpretation; use broad fallback keys only within that same compatibility boundary. Prefer official setup actions or package-manager stores and still run a deterministic install after restore.

Candidate action

First classify each cache path. For package-manager download/HTTP stores, prefer the language vendor's setup action or native cache and key it from every governing dependency file; GitHub setup-node explicitly caches the global package-manager store rather than node_modules and supports cache-dependency-path, while setup-python uses dependency-file hashes. For installed dependency trees, virtual environments, native wheels, compiler outputs, or other executable artifacts, use a versioned key such as <schema>-<OS>-<architecture>-<runtime-and-ABI>-<package-manager-and-cache-format>-<lockfile/config-digest>. Include runtime and architecture when they can change binary compatibility; pin the matrix runtime and runner image rather than using an implicit latest. Keep restore/fallback prefixes inside the same OS/architecture/runtime/manager boundary, or omit them for executable artifacts. After any restore, run the package manager's clean or frozen/locked install and validate the resolved graph; a cache hit is only a speed optimization, not proof that the installed tree is compatible. Bump the schema component when the cached path, compression/archive format, toolchain, or key logic changes. In GitLab, use cache:key:files for lockfiles and prefix for job separation, but add explicit environment dimensions when the image/runtime changes them.

Applicability

• CI matrices spanning multiple operating systems, CPU architectures, language runtimes, toolchains, or package-manager versions.
• Dependency download caches such as npm/Yarn/pnpm, pip, Maven/Gradle, Go modules, and similar stores.
• Installed dependency trees, virtual environments, native extensions, compiled outputs, and build caches where runtime or ABI changes can invalidate bytes.
• GitHub Actions and GitLab CI; adapt the key syntax to other CI providers while preserving the compatibility dimensions.

Key findings

• GitHub's official reference recommends keying dependency caches from a runner OS component and a hash of the dependency lockfile; it states that cache matching also considers cache version, and that restore keys are prefix fallbacks returning the newest matching cache. (S1)
• The official actions/cache strategy guide recommends combining multiple factors such as operating system and lockfile, while the setup-node documentation says its cache targets the global package-manager cache rather than node_modules and can be reused between Node.js versions. (S2, S3)
• GitLab's official documentation provides cache:key:files for lockfile-content keys and prefix for job-specific separation, but its examples do not include runtime versions; therefore runtime/image scoping must be added when the cached path is environment-dependent. (S4)
• pip's official documentation says cache structure is an implementation detail that may change between pip versions and warns that a cached pure-Python wheel from an environment lacking an optional C extension can be reused later when compiling the extension would have been possible; it recommends a source-distribution install when that distinction matters. (S5)

Known limitations

• GitHub's dependency-caching reference explicitly demonstrates runner OS plus lockfile hashing, but does not prescribe CPU-architecture, interpreter/runtime-version, or package-manager-version components; those dimensions are an engineering requirement when they affect cached content, not a universal platform rule.
• setup-node says its global package-manager cache can be reused between Node.js versions; that does not establish that node_modules, native addons, or build outputs are safe to share across Node versions.
• GitLab's official examples key from lockfiles and show runtime images, but do not include runtime versions in those example keys; a project must add them when the selected cache path is runtime-sensitive.
• pip documents that cache internals can change between pip versions and gives an optional-C-extension case where a cached pure-Python wheel can suppress a later rebuild; exact cross-platform and cross-architecture reuse rules are not specified on that page.
• Documentation supports proposed guidance only; no target repository, CI runner, cache backend, dependency installation, or compatibility test was executed.

Negative results

• Do not use only a lockfile hash for a cache containing native or runtime-specific installed artifacts when the same lockfile can be built under multiple environments.
• Do not use a broad restore prefix that crosses operating systems, architectures, runtime/ABI families, package-manager generations, or cache schemas for executable artifacts.
• Do not assume a setup action's global download-store cache has the same compatibility behavior as caching node_modules, a virtualenv, vendor/, or compiled build output.
• A cache hit or restored partial cache is not an execution proof; the install and validation still need to run.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This result is based on official GitHub Actions dependency-caching documentation, the official actions/cache and actions/setup-node repositories, official GitLab CI/CD caching documentation, and pip's official caching documentation read on 2026-09-21; no CI workflow or cache was executed.
• The sources establish lockfile/OS keying, restore-prefix behavior, setup-action cache paths, and pip cache caveats; they do not prove compatibility for an unspecified repository, runner image, dependency graph, architecture, or cache backend.

What remains unknown

• The target CI provider, operating-system and architecture matrix, runner image, language/runtime versions, package-manager versions, and exact cache paths are unspecified.
• It is unknown whether the target cache stores download artifacts, installed trees, native wheels/extensions, compiler outputs, or mixed content; this determines which dimensions must be keyed.
• It is unknown which lockfiles, toolchain files, registry configuration, patches, build flags, and environment variables can alter the resolved or compiled bytes.
• It is unknown whether current fallback keys cross compatibility boundaries, whether installs are clean/frozen after restore, and whether cache contents are validated against the intended runtime and lockfile.
• No execution evidence establishes cross-runtime, cross-architecture, cross-manager, or cache-corruption behavior for the target workload.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Dependency caching reference - GitHub Docs · official_documentation · accessed 2026-09-21
• S2 actions/cache caching strategies · official_repository · accessed 2026-09-21
• S3 setup-node advanced usage: caching packages data · official_repository · accessed 2026-09-21
• S4 Caching in GitLab CI/CD · official_documentation · accessed 2026-09-21
• S5 Caching - pip documentation · official_documentation · accessed 2026-09-21