Cache key turnover planning

Build Cache Capacity & Churn Planner

Estimate how quickly new cache keys consume capacity and whether a quota can preserve the desired reuse window before eviction.

Decision guide

Size cache history from keys that actually turn over

What this tool helps you decide

This planner determines whether a cache quota can preserve a desired number of days of newly created build-cache entries. Unlike a build-time savings calculator, it focuses on capacity, key churn, and the reuse window that survives before eviction or expiry. It is useful for dependency archives, compiler caches, package downloads, container build caches, and other reusable job state keyed by operating system, architecture, toolchain, lockfile, branch, or content hash.

Before you start

Measure an average stored cache entry from the provider or cache backend rather than the uncompressed directory. Count jobs that can read or create this cache class. Inspect logs for exact-key hits, fallback hits, misses, and saves, then estimate the percentage of jobs that create a genuinely new key. Choose the lifetime needed to bridge weekends, release branches, dependency-update cadence, or typical contributor return time. Copy the relevant quota and subtract unrelated cache classes with the other-usage field.

How the calculation works

New entries per day equal cache-eligible jobs multiplied by the new-key percentage. Daily storage churn multiplies new entries by average stored entry size. Desired footprint is daily churn multiplied by desired lifetime. Usable quota applies the free-space reserve and subtracts other cache usage. The effective cache window divides usable quota by daily churn, while supported entries divide usable quota by entry size. Headroom compares desired footprint with usable capacity.

How to interpret the results

If the desired footprint fits, the quota can theoretically preserve the selected window under stable churn. That does not guarantee cache hits: a retained key may never be requested again, while a fallback key can remain useful beyond one exact revision. If effective days are lower than desired, first inspect why keys change. A high new-key rate caused by timestamps, commit identifiers, or overly broad invalidation can waste storage and eliminate reuse even after adding capacity.

Worked example

Forty eligible jobs per day with a 25% new-key rate create ten entries daily. At 2.5 GB per entry, daily churn is 25 GB and a 14-day window needs 350 GB. A 500 GB quota with 15% reserved leaves 425 GB; subtracting 50 GB of other caches leaves 375 GB. The desired window fits with 25 GB headroom, supports about 150 entries, and represents roughly 15 days of churn.

Assumptions and limitations

The calculation assumes stable entry size, job cadence, and new-key rate. It does not simulate least-recently-used order, branch fallback rules, restore prefixes, deduplication, compression variance, provider eviction timing, concurrent uploads, overwrite behavior, download bandwidth, or build-time benefit. A zero new-key rate produces no modeled capacity growth but may reflect an unrealistic sample. Observe several representative days before treating the result as a capacity commitment.

Next steps

Stabilize cache keys around inputs that truly invalidate reusable work. Split very different cache classes so a large low-value entry cannot evict a small high-value one, and record hit type as well as hit rate. Re-run after dependency or platform matrices change. Use the Runner Disk Capacity Checker to include the restored cache in peak local workspace, and use the CI Artifact Retention Planner only for outputs preserved after a job rather than inputs intended for reuse.