Build Cache Recovery Playbook

How It Works

Caches should be deterministic and keyed on lockfiles. This recipe helps teams avoid

"random cache" behavior and introduces a safe busting strategy.

Triggers

• CI failures appear after caching was added
• "Delete cache and rerun" becomes the default fix
• Dependency install inconsistencies appear across branches

Steps

1. Key caches on lockfiles (and include toolchain version in the key when relevant).
2. Add restore-key fallbacks that are safe (prefix matches) but not overly broad.
3. Detect cache-hit vs cache-miss and log it in job output.
4. Add a "cache reset" workflow that:

• invalidates a specific cache namespace,
• reruns the workflow once,
• records the incident.

1. Add guardrails: never cache mutable build outputs unless you can guarantee correctness.

Expected Outcome

• Caching speeds builds while avoiding opaque breakage.
• Cache-related failures become diagnosable and recoverable quickly.

Example Inputs

• "Our CI got faster with cache, but now we see weird install failures."
• "Different branches restore different caches unpredictably."
• "We need a safe way to invalidate caches when needed."

Tips

• The goal is not "always hit cache," it's "always be correct."