GitHub Actions cache: keys, scopes and the limits that decide a hit

A GitHub Actions cache is a keyed, immutable archive that is scoped to a single repository, with a default size limit of 10 GB and an expiration of 7 days without a read. Cache misses are not errors; instead, the step prints a line, exits with a zero status, and hands over the installation files.

The lookup process first attempts to use the exact provided key, and if it cannot find it, it tries the restore-keys listed in the order they were provided, treating each as a prefix. The most recently matching entry is then restored, and the cache-hit flag is set to false, triggering a save step that writes a fresh entry under the exact key.

Each cache entry is an archive stored against an exact string, which means even a single character difference results in a complete miss. This design is why caching is a significant speed-up for most pipelines, but also the quietest way to experience delays when keys are not designed properly.

The key must include every input that changes what ends up in the cached directory. If an input changes but the key remains the same, the new content is never stored, and the next run will restore the old content forever. This design rule emphasizes that every input affecting the cached directory should be included in the key.

Using an artifact as a cache works, but it costs additional storage space. On the other hand, using a cache as durable storage is unreliable, as caches are evicted when they reach the 10 GB limit or after 7 days of inactivity. Therefore, it is essential to understand the distinction between caches and artifacts and use them appropriately in GitHub Actions workflows.