Agent GitHub Actions Cache Keys and Restore Keys

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

GitHub Actions cache key evidence helps agents decide whether a slow or stale CI run came from a cache miss, a partial restore, or an immutable cache that needs a new key.

## Core Explanation

CI cache failures often look like package-manager failures. A workflow can restore a partial cache through `restore-keys`, miss an exact key, or keep using an old cache because existing cache contents are immutable.

Agents should collect the cache action version, `key`, `restore-keys`, `path`, branch, runner OS, lockfile hash, cache hit output, and dependency install logs. A cache hit is not proof that the cache is correct; it only proves that the lookup matched the cache key.

## Source-Mapped Facts

- GitHub Actions dependency caching documentation says the cache action first searches for an exact match to the provided key. ([source](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching))
- GitHub Actions dependency caching documentation says restore-keys are checked sequentially for partial matches when no exact cache match exists. ([source](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching))
- GitHub Actions dependency caching documentation says an exact match to the provided key is considered a cache hit. ([source](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching))
- GitHub Actions dependency caching documentation says users cannot change the contents of an existing cache and should create a new cache with a new key instead. ([source](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching))
- The actions/cache repository describes the action as caching dependencies and build outputs in GitHub Actions. ([source](https://github.com/actions/cache))

## Further Reading

- [GitHub Actions Dependency Caching](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)
- [actions/cache Repository](https://github.com/actions/cache)