Build Artifact Storage Calculator
Estimate retained CI artifact storage from build cadence, retention, active refs, compression, caches, reserve, and quota headroom.| Layer | Storage | Detail | Copy |
|---|---|---|---|
| {{ row.layer }} | {{ row.storage }} | {{ row.detail }} |
| Policy knob | Current value | Storage effect | Operator note | Copy |
|---|---|---|---|---|
| {{ row.knob }} | {{ row.value }} | {{ row.effect }} | {{ row.guidance }} |
Introduction
The storage cost of build artifacts rarely comes from one impressive archive. It comes from ordinary files being produced again and again: compiled binaries, zipped web builds, test reports, coverage output, screenshots, installers, documentation bundles, and release candidates. Each successful job can leave a copy behind, and that copy stays billable or quota-counted until a retention rule, cleanup job, or manual action removes it.
Continuous integration (CI) storage grows by multiplication. Artifact size, builds per day, days kept, and active refs all compound before caches, latest-successful protection, or reserve headroom are added. A 180 MiB artifact feels modest in isolation, but dozens of daily uploads across several branches can become hundreds of GiB before anyone notices the quota warning.
| Planning factor | What it represents | Common mistake |
|---|---|---|
| Retention window | How long generated files remain available before normal expiry. | Using one policy for both release evidence and short-lived preview artifacts. |
| Active ref | A branch, tag, merge-request ref, or release line that produces retained artifacts. | Leaving stale branches in the estimate after the work has merged or been abandoned. |
| Latest-successful protection | The newest successful artifact kept for each ref even when ordinary expiry removes older copies. | Forgetting that one protected artifact per ref can add up across many refs. |
| Cache storage | Dependency or build cache data that often grows near artifact activity. | Treating caches as if they obey the same cleanup policy as artifacts. |
Good artifact planning starts by separating files that deserve different treatment. Release evidence, signed installers, and audit reports may need long retention or a separate archive. Pull-request previews, intermediate logs, and branch-specific debug output usually need a shorter window. Averaging all of those together can hide the policy change that would reduce storage fastest.
A storage estimate is not proof that a CI account is clean. Cleanup delays, failed expiry jobs, manual keep actions, unusually large release days, and stale refs can all make real usage higher than the modeled run rate. Reserve allowance exists because storage systems rarely behave as neatly as the policy written beside them.
How to Use This Tool:
Start with the fields that describe normal artifact production, then add quota and reserve values only when they are part of the planning question.
- Enter Artifact size in MiB/build. Use the average retained archive size for the jobs being planned, not a one-time release outlier.
- Set Builds per day, Retention period, and Active branches or refs. The Retained artifact jobs row should match those three values multiplied together.
- Set Compression savings. Use 0 when the artifact size already comes from stored compressed archive reporting.
- Set Cache multiplier. Use 0 for artifact-only sizing, or enter a multiplier such as 0.25 when caches are expected to add 25% of retained artifact storage.
- Choose Latest artifact retention. When it is enabled, Latest-successful protection adds one effective artifact per active ref outside the normal retention total.
- Open Advanced when you need an Export label, Storage quota, Monthly growth, or Reserve allowance. A positive quota turns on quota percent, quota headroom, and the quota status badge.
- If the result looks impossible, check the input boundaries first. Negative artifact sizes and build rates count as 0, retention days and refs cannot go below 1, and percentage fields are clamped to their supported ranges.
Use Storage Footprint to audit the current total, Retention Policy to see which setting is driving it, Retention Growth Curve for month-by-month growth, and Artifact Mix for the share from artifacts, latest protection, caches, and reserve.
Advanced Tips:
- Run separate estimates for release artifacts and preview artifacts when their retention windows or storage policies differ.
- Use the Storage quota field only when it matches a real project, organization, or billing limit. A zero quota intentionally disables quota status checks.
- Add a reserve allowance when cleanup jobs run late, artifacts are manually kept, or release days create larger archives than the average build.
- Use Monthly growth for a run-rate forecast, not for policy changes. Retention days and active refs stay fixed in the growth curve.
- Review latest artifact retention when active refs exceed 20. One protected archive per ref can become a branch hygiene problem.
- Compare the Artifact Mix chart with provider storage reports before changing quotas so caches, protected latest artifacts, and reserve are not mistaken for normal retained artifacts.
Interpreting Results:
Total storage is the main planning number after retained artifacts, latest-successful protection, caches, and reserve are added. Retained artifact jobs explains the scale behind that number. When it is high, lowering artifact size is only one option; fewer artifact-producing jobs, shorter retention, fewer active refs, or stricter branch cleanup may produce a larger reduction.
The quota badge is a warning aid, not a capacity guarantee. Over quota means modeled total storage is greater than the positive storage quota. Quota watch means total storage is above 80% of quota but not above it. Storage planned only means those quota checks did not trigger, so compare the result with the CI provider's storage reporting before raising or lowering a real quota.
Zero values deserve a deliberate review. A Cache multiplier of 0 removes caches from the estimate, a Reserve allowance of 0 assumes no cleanup lag or release spike, and a Storage quota of 0 disables quota comparison. Those choices are valid only when they match the planning question.
| Result area | What it means | What to verify next |
|---|---|---|
| Total storage | All modeled artifact, latest, cache, and reserve storage. | Compare with storage reporting and the configured quota. |
| Retained artifact jobs | Builds per day multiplied by retention days and active refs. | Confirm that only jobs uploading retained artifacts are counted. |
| Latest-successful protection | One protected artifact per active ref when keep-latest behavior is enabled. | Check whether feature refs need the newest successful archive. |
| Caches | Additional storage estimated from retained artifacts and the cache multiplier. | Compare with cache reporting, or set the multiplier to 0 for artifact-only planning. |
| Quota headroom | The positive space left under a configured quota. | Leave enough headroom for expiry lag and unusually large release builds. |
Technical Details:
Artifact storage is a rolling-window capacity calculation. Every artifact-producing build contributes one stored archive until the retention window removes it. Build cadence, retention length, and active refs multiply together before size is applied, which is why branch cleanup and artifact upload rules often matter as much as compression.
Stored size starts with the per-build archive size after compression savings. Latest-successful protection is counted separately because some CI systems keep the newest successful artifact for each ref outside ordinary expiry. Cache storage is also separate because dependency caches and build caches often grow with CI activity but use their own cleanup rules.
Formula Core
The governing calculation combines normal retained artifacts, protected latest artifacts, cache allowance, and reserve allowance in MiB, then displays larger totals in GiB or TiB.
| Symbol | Meaning | Calculation note |
|---|---|---|
| A | Artifact size in MiB/build. | Average uploaded archive size before compression savings, unless the stored compressed size is already known. |
| P | Compression savings percent. | Clamped from 0% to 100%; 0 means no reduction from the entered size. |
| E | Effective stored artifact size. | Artifact size after compression savings. |
| B, D, F | Builds per day, retention days, and active refs. | Their product is Retained artifact jobs. |
| L | Latest-successful protection. | E multiplied by active refs when enabled; otherwise 0. |
| C | Cache allowance. | Normal retained artifact storage multiplied by the cache multiplier. |
| S | Reserve allowance. | Reserve percent multiplied by retained artifacts, latest protection, and caches. |
| T | Total storage. | Displayed in MiB, GiB, TiB, or PiB using binary 1,024-unit steps. |
With 180 MiB artifacts and 18% compression savings, effective artifact size is 147.6 MiB. At 36 builds per day, 14 retention days, and 6 refs, Retained artifact jobs is 3,024 and normal retained artifacts are about 435.88 GiB. A 0.25 cache multiplier adds about 108.97 GiB, and latest-successful protection adds about 886 MiB before any reserve.
| Rule | Boundary | Planning effect |
|---|---|---|
| Artifact size and builds per day | Values below 0 count as 0. | Prevents negative storage or negative retained job counts. |
| Retention period and active refs | Minimum 1, rounded down to a whole number. | Models at least one retained day and one artifact-producing ref. |
| Compression savings | 0% to 100%. | Reduces effective artifact size before retention math. |
| Monthly growth and reserve allowance | 0% to 300%. | Growth affects the forecast curve; reserve raises the current total. |
| Quota watch | Total storage is greater than 80% of a positive quota. | Flags cleanup or quota review before the modeled total exceeds quota. |
| Over quota | Total storage is greater than a positive quota. | Indicates the modeled policy needs cleanup, a higher quota, or a smaller artifact footprint. |
| High retained build count | Retained artifact jobs exceed 10,000. | Prompts a cleanup and expiry review because many stored archives are being modeled. |
| Many refs with latest protection | Latest retention is enabled and active refs exceed 20. | Highlights branch/ref hygiene because each ref adds a protected latest artifact. |
The growth forecast compounds artifact size and build cadence for months 0 through 12. Retention days and active refs stay fixed in that projection, so the curve is a run-rate estimate, not a prediction that branch count or retention policy will change on its own.
Privacy Notes:
No artifact file upload is required, and no CI account is scanned. The calculation works from typed planning values. Treat project labels, exported tables, chart downloads, and copied JSON as shareable artifacts only after removing sensitive repository or product names.
Worked Examples:
Default web application run rate
With 180 MiB artifacts, 36 builds per day, 14 retention days, 6 active refs, 18% compression savings, a 0.25 cache multiplier, and latest-successful protection enabled, Total storage is about 545.72 GiB. Retained artifact jobs is 3,024, Retained artifacts is about 435.88 GiB, Caches is about 108.97 GiB, and Latest-successful protection is about 886 MiB.
Quota watch before a hard limit
A project with 160 MiB artifacts, 22 builds per day, 21 retention days, 8 refs, 15% compression savings, a 0.30 cache multiplier, latest protection, a 10% reserve, and an 850 GiB quota lands near 703.12 GiB. The status becomes quota watch because the estimate is about 82.7% of quota, with about 146.88 GiB of Quota headroom left.
Release project over quota
A mobile release project with 420 MiB artifacts, 18 builds per day, 30 retention days, 9 refs, 10% compression savings, a 0.40 cache multiplier, latest protection, a 15% reserve, and a 2,500 GiB quota reports about 2.82 TiB. The status becomes over quota because total storage is about 115.7% of quota.
Many preview refs without latest protection
A documentation preview workflow with 85 MiB artifacts, 24 builds per day, 7 retention days, 18 active refs, no compression savings, no caches, and latest retention disabled reports about 251.02 GiB. Latest-successful protection and Caches both show 0 MiB, so the first cleanup path is stale refs and unnecessary artifact-producing jobs.
Troubleshooting a surprisingly large total
If 300 MiB artifacts, 20 builds per day, 30 retention days, 25 refs, a 0.50 cache multiplier, latest protection, a 20% reserve, and a 5,000 GiB quota produce about 7.73 TiB, the Retained artifact jobs row explains the main pressure: 15,000 retained jobs before caches and reserve. Check stale refs and artifact upload rules before treating the answer as a reason to raise quota.
FAQ:
Why is retained artifact jobs so important?
Retained artifact jobs is the multiplier formed by builds per day, retention days, and active refs. If that row is large, storage can stay high even when each artifact archive looks reasonable.
Should artifact size be entered before or after compression?
Enter the average source artifact size and use Compression savings when archive compression or deduplication should reduce stored size. If the number already comes from stored archive reporting, set compression savings to 0.
What does latest artifact retention change?
When enabled, Latest-successful protection adds one effective artifact per active ref outside normal retained artifacts. When disabled, latest artifacts are modeled as expiring normally.
Why can caches make the estimate higher than artifact storage alone?
Cache multiplier adds cache storage as a share of retained artifacts. A 0.25 multiplier adds 25% of normal retained artifact storage, which can be large when the retained job count is high.
Why does quota watch appear before the quota is exceeded?
Quota watch appears when Total storage is above 80% of a positive Storage quota. It is an early warning so cleanup, retention changes, or quota planning can happen before the modeled total crosses the limit.
What should I check if the number looks impossible?
Check Retained artifact jobs first, then active refs, retention period, cache multiplier, reserve allowance, and whether artifact size is already compressed. A long retention window or stale refs can make ordinary build archives look excessive.
Are artifact files uploaded for this calculation?
No artifact files are uploaded and no CI provider account is queried. The calculator uses typed planning values, then returns tables, charts, and JSON from those values.
Glossary:
- Artifact
- A retained file or archive produced by a build, test, publish, or release job.
- Retention window
- The number of days artifacts remain stored before normal expiry or cleanup.
- Active ref
- A branch, tag, merge-request ref, or release line that produces and retains its own artifacts.
- Retained artifact jobs
- The build count inside the retention window after builds per day, days kept, and active refs are multiplied.
- Latest-successful protection
- Behavior that keeps the newest successful artifact for each ref outside ordinary expiry.
- Cache multiplier
- A planning factor that adds cache storage as a share of retained artifact storage.
- Reserve allowance
- Extra storage added for cleanup lag, failed expiry jobs, or unusually large releases.
- Quota headroom
- The remaining storage under a positive quota after the modeled total is counted.
References:
- Configuring the retention period for GitHub Actions artifacts and logs, GitHub Docs.
- Job artifacts, GitLab Docs.
- Dependency caching reference, GitHub Docs.