Dependency Caching, Cache Keys, Restore Strategies, and Performance: Core Concepts and Mental Model

1. The practical problem: repeated dependency work is expensive, but correctness cannot depend on reuse

A fresh GitHub-hosted runner starts without the dependency downloads from the previous run. Re-downloading the same wheels, npm tarballs or Maven dependencies wastes time and network bandwidth. Caching solves that performance problem by saving selected reusable files and restoring them into a later run.

The critical boundary is that a cache is best effort. It can miss because the key changed, the cache version changed, branch scope prevents access, the entry expired, storage pressure evicted it, or a low-trust run has read-only access. A correct workflow must still be able to reconstruct the required dependencies from source-controlled inputs when no cache is available.

2. Causal model: dependency contract → key/version/scope → restore → install/build → optional save

First define the dependency contract: lockfile or equivalent manifest, exact toolchain, operating system/architecture when binaries differ, and any configuration that changes what is downloaded or compiled. The workflow derives a primary key from those inputs. The cache service searches that key and cache version in the permitted scope; if there is no exact match, ordered restore prefixes may provide older acceleration state. The package manager then reconciles restored files with the current dependency contract. Only after a successful job may the current cache action save a new primary-key entry.

flowchart TD
  A[Lockfile + toolchain + OS/arch] --> B[Primary cache key]
  B --> C[Cache key + version + ref scope]
  C --> D{Exact match?}
  D -->|Yes| E[Restore exact cache]
  D -->|No| F{Restore-key prefix match?}
  F -->|Yes| G[Restore older/partial cache]
  F -->|No| H[Start without cache]
  E --> I[Package manager validates current inputs]
  G --> I
  H --> I
  I --> J[Build/test]
  J --> K{Job succeeds and key absent?}
  K -->|Yes| L[Save new cache entry]
  K -->|No| M[No new cache save]

The package manager or build system remains the correctness authority. Restored bytes are an optimization input, not proof that the current lockfile has been satisfied.

3. Record the state that explains a cache decision

4. A key is part of the correctness boundary

A useful dependency key changes when a correctness-relevant input changes. For a Python wheel/download cache, a reasonable key includes runner OS/architecture, Python major/minor and a lockfile hash. The exact syntax is less important than the invariant: two runs that can require incompatible cached bytes must not be forced to share the same exact key.

- id: cache
  uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
  with:
    path: ${{ steps.pip.outputs.cache_dir }}
    key: >-
      pip-${{ runner.os }}-${{ runner.arch }}-py${{ steps.py.outputs.minor }}-${{ steps.lock.outputs.sha256 }}
    restore-keys: |
      pip-${{ runner.os }}-${{ runner.arch }}-py${{ steps.py.outputs.minor }}-

5. Exact hit, fallback and miss are three different observations

Current actions/cache first looks for the primary key and cache version, then prefix matches, then ordered restore-keys. If the current branch has no permitted match, GitHub can repeat the lookup against the default branch subject to cache-scope restrictions. An exact primary-key match reports cache-hit as 'true'. A restored prefix/restore-key match reports 'false'. No restored cache yields an empty output.

That distinction matters. A fallback cache is intentionally stale relative to the current primary key, so the dependency tool must fill or replace missing data. Even an exact hit normally does not justify skipping dependency installation when the cached path is merely a package-manager download cache.

6. Same text key can still miss: cache version and scope

GitHub also stamps cache entries with a cache version derived from the cached paths and compression/archive behavior. This prevents a run from restoring an entry it cannot correctly unpack into the requested path. Branch/tag/PR scope adds another boundary: caches are not a repository-wide anonymous bucket.

When a key appears “identical” but restore still misses, inspect the cache version and ref before deleting anything. A missing cache can be correct behavior rather than corruption.

7. Cache, artifact and output solve different persistence problems

8. Restored cache contents are untrusted input

Caches can be readable from broader workflow contexts than the job that created them, including pull-request scenarios that can restore base/default-branch caches. Never place access tokens, private keys, .env files or other secrets in cached paths. A poisoned cache can also become an execution path if a trusted workflow executes binaries or scripts restored from a cache without validation.

Prefer caching package-manager download stores or deterministic intermediate state whose consumers revalidate it. Be especially cautious with compiled build-output caches that embed environment variables, compiler flags, absolute paths or trust-sensitive generated code.

9. Read-only cache inspection before tuning or deletion

Cache metadata can explain a surprising restore without mutating anything. In an authorized disposable repository, inspect IDs, keys, refs, versions, sizes and access times before changing keys or deleting entries.

GH_REPO='OWNER/gha-cache-lab'

gh api   -H 'X-GitHub-Api-Version: 2026-03-10'   "repos/$GH_REPO/actions/caches?per_page=100"   --jq '.actions_caches[] | {id,ref,key,version,size_in_bytes,created_at,last_accessed_at}'

10. Performance state is also storage state

GitHub currently removes cache entries after the configured inactivity period and evicts older entries when repository cache storage exceeds its limit. The default remains 7 days of inactivity and 10 GB per repository, while eligible plans can configure larger limits. Therefore “the warm run will always hit next week” is not a valid invariant.

Measure cache hit rate, restore duration, install duration and cache size before increasing storage. A large cache that is slow to transfer can make a workflow slower than rebuilding or re-downloading.

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.