GitHub Actions / Reusable automation and scoped authority / Lesson 7

Cache keys, restore paths, and dependency integrity

Accelerate acquisition while preserving correct behavior when no cache exists.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Review exact and fallback cache selection.
Separate cache identity from dependency and artifact identity.

Choose what the cache contains

Actions caches are reusable storage intended to reduce repeated work such as downloading dependencies. First identify whether the cached directory contains verified downloads, compiled objects, a virtual environment, or generated application output. These have different compatibility and trust requirements. Parcel’s reviewed dependency lock remains authoritative even when an old cache is restored. A missing cache should make acquisition slower or produce a clear network failure, not secretly select another dependency set. Never store credentials or rely on a cache as the sole copy of a release package.

Understand the selected cache, not just the requested key

The cache mechanism first looks for a matching key under its documented scope and version behavior, then may use partial or restore-key matches. The exact-hit output distinguishes an exact match from other restoration outcomes; it is not a statement that dependencies are correct. A fallback can usefully supply older downloads if the package manager validates current requirements afterward. Restoring an entire executable environment under a broad fallback is riskier because stale files may remain active even when the dependency installer reports success.

Include relevant compatibility dimensions

A key commonly incorporates runner operating system, dependency-lock content, and a toolchain or cache-format distinction when relevant. Architecture matters for native output. Branch names can separate usage but do not describe byte compatibility. The following complete local program models a lock-sensitive key and demonstrates that changing a dependency changes selection. The short digest is a readable teaching key, not an integrity check for the packages themselves. A real acquisition step must verify package content using the package manager’s supported mechanism.

python Model three cache selection dimensions

import hashlib
def cache_key(os_name, architecture, lock):
    return f"{os_name}-{architecture}-" + hashlib.sha256(lock.encode()).hexdigest()[:10]
first = cache_key("linux", "x64", "parcel-format=3")
print(first == cache_key("linux", "x64", "parcel-format=3"))
print(first == cache_key("linux", "arm64", "parcel-format=3"))
print(first == cache_key("linux", "x64", "parcel-format=4"))

Expected output

True
False
False

The program never restores or saves a cache. Actual Actions cache versioning, branch scope, archive format, and action compatibility require the official reference.

Review writers and low-trust consumers

Cache access depends on event, ref, repository policy, and current platform protections. Do not assume a cache is private merely because its key is obscure. Untrusted jobs must not supply executable state to privileged promotion without an appropriate trust design. Review current low-trust event restrictions and any cache-access policy rather than relying on remembered defaults. Keep release authority out of dependency-validation jobs where possible. The conceptual split below expresses a trust goal, not a claim that a naming convention enforces isolation.

text Cache trust goals

proposal path: unprivileged dependency validation
trusted path: reviewed inputs and verified acquisition
release package: retained by explicit candidate identity

Separate names alone do not enforce access. The selected Actions service, event policies, runner model, and cache implementation determine which content can cross these boundaries.

Measure restoration and test the cold path

Compare restore, dependency acquisition, save, and total job time. Large archives can take longer to transfer than fresh downloads. A cache-hit percentage is useful only when feedback actually improves. Periodically validate with no cache in an authorized lab to expose undeclared inputs. If a file is missing, distinguish a dependency acquisition problem from a missing producer artifact before deleting caches. Clearing everything can temporarily hide a race without explaining it, and can impose unnecessary load on dependency sources.

Common errors and fixes

cache-hit is treated as dependency verification.

Why it happens: Selection success was confused with integrity and compatibility.
How to fix it: Run the current locked acquisition and supported integrity checks.
Prevent it next time: Keep dependency policy authoritative after every restore.

A native environment moves between x64 and arm64.

Why it happens: The key omits architecture or other binary compatibility inputs.
How to fix it: Separate entries using the relevant compatibility contract.
Prevent it next time: Document whether cached content is portable source or executable output.

A release works only when a previous cache exists.

Why it happens: Required application output is hidden in disposable acceleration storage.
How to fix it: Produce and transfer the required artifact explicitly.
Prevent it next time: Validate a cold path and retain release candidates separately.

Check your understanding

1. A fallback restores last week’s package downloads. Must the build reject them all?

Show worked solution

Not necessarily. If they are immutable downloads and the current package manager verifies content against the reviewed lock, useful entries can be reused and missing ones fetched. Stale executable environments need a stricter compatibility assessment.

2. A cache saves twenty seconds of downloads but adds forty seconds of archive transfer. What should be optimized?