The default per-repository cache storage limit is 10 GB at no cost; as of November 2025, enterprise, organization, and repository admins can configure this limit upward with additional storage billed beyond the included 10 GB
Configure cache policy limits in repository Settings > Actions > Caches (for repositories) or via the organization-level Actions settings; set both a size eviction limit (GB) and a retention limit (days)
The eviction interval was changed to hourly in 2025; when a repo's total cache size exceeds its limit, least-recently-used entries are evicted automatically within that hour
Caches that have not been accessed within the configured retention period (default 7 days) are also evicted regardless of total size; always re-save frequently used caches (e.g., node_modules) on each run to reset the access timestamp
Use actions/cache@v4 and set a restore-keys fallback list to allow partial cache hits when the exact key misses: restore-keys: | npm-deps- ; this returns the most recent matching prefix entry
List and manually delete caches via the REST API (GET /repos/{owner}/{repo}/actions/caches) or the GitHub CLI (gh cache list, gh cache delete) to reclaim space before the automated eviction runs
Known gotchas
Cache keys are scoped to the branch; caches created on a PR branch are not accessible on the default branch and vice versa — this is intentional isolation but often surprises users expecting cross-branch cache sharing
actions/cache does not fail a workflow when a cache miss occurs; check the cache-hit output variable in subsequent steps if your workflow logic depends on knowing whether a cache was restored
Pushing frequently to many short-lived branches can fill the repository cache quota quickly with branch-scoped entries; use a common restore-keys prefix based on the lock file hash so stale branch caches are not created per commit
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp