Equation audit
Developer Build Storage & Retention Formulas
Check the deterministic equations used to separate binary source history, retained outputs, cache churn, image layers, and runner peaks.
Units and accounting boundaries
The cluster uses decimal gigabytes: 1 GB is 1,000,000,000 bytes and 1 TB is 1,000 GB. Provider dashboards may display decimal GB, binary GiB, or a product-specific billed quantity. Convert measurements to one unit before comparison. A negative headroom value means modeled demand exceeds usable capacity; it does not imply that a provider permits negative usage.
| Planning class | Core equation | Boundary to preserve |
|---|---|---|
| Git LFS retained storage | current GB + changed GB/release × releases/month × min(retention months, horizon months) | Changed unique version bytes are not the same as full checkout payload. |
| Git LFS monthly downloads | full-download payload GB × full downloads/month | Whether a fetch counts is determined by current host documentation. |
| CI artifact rolling storage | stored GB/run × producing runs/day × retention days | Use uploaded compressed size and separate policy classes. |
| Build cache desired storage | entry GB × jobs/day × new-key fraction × desired days | Only newly saved keys create modeled churn. |
| Registry projected storage | shared base copies + unique GB/image × retained images + unique GB/image × pending-GC images | Deduplication scope and GC timing are platform evidence. |
| Runner concurrent peak | sum(per-job components) × simultaneous jobs | Persistent OS, daemon, log, and abandoned use is subtracted separately. |
Quota reserve and other usage
For artifact and cache quotas, usable capacity for the modeled class is:
usable class GB = quota GB × (1 − reserve percentage ÷ 100) − other usage GB
For a registry with no separately entered other usage, usable registry quota is quota multiplied by the same reserve factor. Reserve is a planning choice, not an official technical threshold. It exists to keep a policy away from a hard stop and should reflect measurement variance, cleanup delay, and service behavior.
Maximum retention and effective cache window
Maximum artifact retention is the floor of usable class GB divided by daily artifact ingest. Rounding downward avoids recommending a partial day as a complete policy setting. The build-cache effective window divides usable cache quota by daily churn and can be fractional because it describes an estimate rather than a configured integer. When daily churn is zero, both values have no finite growth limit under the entered model; that state should trigger a check that the observed key sample is realistic.
Container image layer model
Shared layer GB equals compressed image GB multiplied by the shared percentage. Unique layer GB is the remainder. When the registry is documented to deduplicate across the entered namespace, the model stores one shared base copy. When reuse is documented only inside each repository, it stores one base copy per repository. Retained images equal images per repository per day multiplied by repository count and tagged retention days. Pending-GC images use the same cadence multiplied by the garbage-collection delay.
This is a deliberately transparent approximation. Real manifests can have several partially shared layer families, multi-architecture indexes, signatures, attestations, and changing base versions. A tag can point to an existing digest without creating a new image. Use manifest analysis or the registry's usage report when exact object-level accounting is available.
Runner minimum disk equation
Per-job GB is checkout + LFS + dependencies + restored cache + build output + temporary space. Peak workspace multiplies that sum by concurrency. Usable workspace equals total disk × (1 − reserve fraction) − persistent use. Reversing that equation gives:
minimum disk GB = (persistent use GB + concurrent peak GB) ÷ (1 − reserve fraction)
The denominator must remain positive, which is why the tools cap reserve below 100%. Maximum concurrency is the floor of usable workspace divided by per-job peak. A per-job sum of zero is accepted only when every entered component is genuinely zero; in practice, measure the checkout and temporary state before using that edge case.
Worked cross-check
For a runner with 74 GB per job and four jobs, concurrent peak is 296 GB. A 500 GB disk with 20% reserve and 80 GB persistent use has 500 × 0.8 − 80 = 320 GB of usable workspace, leaving 24 GB. Minimum disk is (80 + 296) ÷ 0.8 = 470 GB. The values are independent of filesystem format, performance, and SSD endurance.
Source hierarchy and limitations
Use current official project or vendor documentation to decide what counts toward a quota, when an object expires, where deduplication applies, and when deleted content is reclaimed. Examples include GitHub's Git LFS billing concepts, the official upload-artifact documentation, and GitLab's container registry storage guide. These formulas do not encode a provider's allowance, price, retention maximum, or billing rule.
Return to the Developer Build Storage Planning hub to run the matching planner. Store measurements, source URLs, and dates with the output so a later reviewer can distinguish a changed workflow from a changed provider rule.