Published · Updated
Is your GitHub Actions cache actually full?
A cache miss can result from more than a key mismatch. Capacity, eviction, branch scope, and where the next build runs can all affect whether an entry is reusable.
Evicted cache entries cannot be restored.
GitHub Actions includes 10 GB of cache storage per repository by default. Administrators can increase the limit; storage used beyond 10 GB is billed. At the configured limit, GitHub evicts entries by last access date, oldest first. Entries not accessed for more than seven days are also removed.
Check cache usage and the entry list in the repository's Actions settings or through GitHub's Actions Cache REST API. Look for large entries, rapid replacement, and a total that stays near the limit. Those patterns can indicate capacity pressure. Compare them with the configured storage limit before changing cache keys.
Repository and branch restrictions can prevent cache reuse.
- Repository: Actions cache is tied to one GitHub repository. It is designed for reuse between that repository’s Actions workflows.
- Branch: workflow runs can restore entries from the current branch, the default branch, and in some cases the pull request's base branch. A cache created on an unrelated branch may be unavailable even when the key matches.
- Version: the cache version includes metadata such as paths and compression. A changed path list can make the visible key look familiar while the stored version no longer matches.
Restored cache can contain code the next build executes.
Do not store credentials or sensitive files in build cache. Limit cache publication from untrusted pull requests, especially when later trusted jobs may execute restored compiler output, scripts, or package-manager state.
Pull requests restore
Give untrusted jobs the minimum access needed to reuse published work.
Trusted jobs publish
Update shared cache from the default branch, release jobs, or another reviewed workflow path.
Use shared cache when builds run outside GitHub Actions.
GitHub Actions cache remains a good fit when every consumer runs inside one repository's Actions workflows. BoringCache for GitHub Actions is useful when the same build state should also be reused in Docker builds, local development, another CI system, or agent sandboxes—and when restore and save credentials need to be separate.
Start with your repository
Run boringcache onboard once. BoringCache finds useful cache state, writes .boringcache.toml, and keeps the same cache names across local builds and CI.