Dependency Caching, Cache Keys, Restore Strategies, and Performance: Configuration, Design Patterns, and Trade-Offs

1. Start with the question “What happens if this cache disappears?”

If the correct answer is “the job becomes slower but still reconstructs the same result,” the data is a good cache candidate. If the answer is “we lose the only copy of the release binary, report or provenance evidence,” it belongs in an artifact or external records system instead.

This single question prevents the most common cache architecture error: using a key-addressed, evictable performance service as authoritative build storage.

2. Decision table: choose the smallest mechanism that preserves correctness

3. Built-in setup-action caching versus explicit cache actions

Current setup actions can manage common package-manager caches: setup-node for npm/Yarn/pnpm, setup-python for pip/pipenv/Poetry, setup-java for Gradle/Maven, setup-go for Go modules, setup-dotnet for NuGet and others. This is often the most maintainable choice because the action knows the package manager's conventional cache location and lockfile hashing model.

- name: Set up Python with built-in pip caching
  uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
  with:
    python-version: '3.13'
    cache: pip
    cache-dependency-path: requirements.lock

- name: Install from the dependency contract
  run: python -m pip install -r requirements.lock

Use explicit actions/cache when you need a custom path, explicit restore-prefix policy, split restore/save steps, lookup-only, fail-on-cache-miss for a deliberately strict offline flow, or richer cache evidence.

4. Restore prefixes trade hit rate for staleness

Restore keys are ordered prefixes. A narrow fallback such as “same OS + same architecture + same Python minor” is easier to justify for pip downloads than a prefix that ignores toolchain and operating system. Every dimension you remove broadens the set of stale bytes eligible for restoration.

The safe production question is not “Can we get more hits?” but “Can the consumer deterministically reject or repair any incompatible state this prefix may restore?” If not, keep the key exact or redesign the cached path.

5. Build-output caches need stronger key contracts

Compiler outputs can depend on more than source and lockfiles: compiler version, target architecture, feature flags, environment variables, generated headers, SDK versions, system libraries and even absolute paths. A build cache key that omits any of these can produce a fast but invalid result.

Prefer tool-native caches that already model those dependencies where possible. If you cache generated build trees directly, document every correctness-relevant input and periodically prove a clean rebuild produces equivalent results.

6. Scope and cross-OS reuse are explicit compatibility decisions

GitHub cache lookup is constrained by ref/branch scope; default-branch entries can be available to other branches under documented rules. This is a security and isolation boundary, not an inconvenience to bypass. Similarly, cross-OS archives are opt-in and require compatible tools/paths. Do not remove runner.os from a key just to force a hit across incompatible dependency stores.

7. Storage and retention affect reliability and cost

The current default cache inactivity period is 7 days and default storage limit is 10 GB per repository. Eligible GitHub.com repositories can opt into larger retention and storage, which can introduce billing. Very broad keys can create cache thrashing; very specific keys can create thousands of rarely reused entries.

Track cache size, last-access time, hit rate, restore time and install/build savings. Optimize the critical path, not the cache-hit percentage by itself.

8. Worked scenarios

9. Cache rollback means bypass/re-key, not pretending old bytes never existed

If a cache is suspected of poisoning or hidden-environment dependence, preserve its ID/key/version/ref and the failing run first. Then temporarily bypass it, tighten the key or use a new bounded epoch while the cause is investigated. Exact deletion can be appropriate after evidence is captured, but “delete all caches” destroys useful diagnostic state and can create a thundering herd of cold installs.

Knowledge check

Official references and version notes

• GitHub Docs — Dependency caching — cache purpose, artifact distinction and cache-security boundary.
• GitHub Docs — Dependency caching reference — key matching, restore keys, branch scope, versioning, limits and eviction.
• GitHub Docs — Managing caches — read-only inspection and exact cache deletion.
• actions/cache v6.1.0 — explicit cache action pinned to 55cc8345863c7cc4c66a329aec7e433d2d1c52a9.
• actions/setup-python v7.0.0 — Python setup action pinned to 5fda3b95a4ea91299a34e894583c3862153e4b97.
• setup-python dependency caching — built-in pip/pipenv/Poetry caching and cache-dependency-path.