Build Artifact Storage Calculator

Build artifacts are the files a continuous integration run saves after compiling, packaging, testing, or publishing evidence from a build. They may be ZIP archives, binaries, coverage reports, screenshots, documentation bundles, or release candidates. Artifact storage grows when those files are produced often, kept for many days, repeated across many branches or refs, or protected after the normal expiry window.

Artifact retention matters because CI systems can turn a small per-build output into a large rolling storage footprint. A 180 MiB archive is modest for one job, but 36 artifact-producing builds per day across 6 active refs over 14 days already means 3,024 retained artifact jobs before caches, latest successful artifacts, and reserve are added. That kind of run rate can affect billing, quota alerts, cleanup policy, and how much evidence stays available for debugging.

Good artifact storage planning separates release evidence from temporary build output. Some artifacts must be retained for deployment rollback, audit, or customer delivery. Others only need to survive long enough for a downstream job, a failed-test review, or a pull-request preview. Keeping every artifact for the same period can hide the real cost of noisy validation jobs.

The result is an estimate, not a live scan of a CI account. It is strongest when the input values come from recent pipeline history: average uploaded artifact size, builds that actually upload retained files, active refs during the retention window, and the retention behavior used by the CI platform. Cleanup delays, manual holds, failed expiry jobs, and unusually large release builds should be covered with a reserve rather than ignored.

Technical Details:

Artifact storage is a rolling-window calculation. Each artifact-producing build contributes one stored archive until the retention window expires it. Multiplying build cadence by retention days and active refs gives the retained job count, and multiplying that count by the effective stored artifact size gives the main retained footprint.

Compression savings reduce the per-build artifact before the retention total is assembled. Cache storage is modeled separately because dependency caches and build caches often scale with artifact activity but are governed by different cleanup behavior. Latest-successful protection adds one retained artifact per active ref when the platform keeps the newest successful output outside normal expiry.

The storage estimate uses binary units. One GiB is 1,024 MiB. That matches the way many CI billing and reporting pages describe retained storage, but the source artifact number still needs a consistent unit label. Mixing MB, MiB, GB, and GiB in the same plan can move the result enough to matter near a quota boundary.

The main formula combines the normal retention window, protected latest artifacts, caches, and optional reserve.

Growth forecasting compounds both artifact size and build cadence. A monthly growth value of 8% does not merely add 96% at month 12; it compounds the run rate and the archive size each month. Retention days and active refs stay fixed in the forecast, so the curve is a storage run-rate projection rather than a branch-count prediction.

Quota status uses the total storage after reserve. A result above the quota is marked over quota. A result above 80% of a positive quota is marked quota watch. High retained job counts and many active refs can also produce warnings because artifact cleanup policies often behave differently under heavy branch churn.

Everyday Use & Decision Guide:

Begin with a current production run rate. Set Artifact size to the average uploaded archive size, not the largest one-off release. Set Builds per day to successful jobs that upload retained artifacts per ref. If only some jobs publish artifacts, count those jobs rather than every CI run.

Retention period and Active branches or refs usually drive the first policy discussion. A short-lived pull-request preview can use fewer retained days than a release candidate, and stale feature refs should not silently count the same as active release refs. Keep latest successful per ref should stay enabled only when downstream jobs, previews, or rollback procedures need that newest archive after normal expiry.

• Use Compression savings as 0 when the artifact size already reflects the stored archive size.
• Use Cache multiplier as 0 for artifact-only planning, or 0.25 when caches are expected to add about a quarter of retained artifact storage.
• Enter Storage quota when the result needs a clear over quota or quota watch cue.
• Add Reserve allowance when cleanup jobs are delayed, release builds are much larger than ordinary builds, or expiry is known to lag.
• Use Monthly growth only for the Retention Growth Curve; it does not change the month-zero storage footprint.

The calculator is a good fit for policy reviews, quota planning, and before-and-after comparisons when changing retention days or ref cleanup. It is not a replacement for a CI inventory export. If manual artifact locks, release leases, or platform-specific exceptions exist, include those as reserve or run a separate platform report before treating the number as final.

A common misread is to treat Total storage as proof that every artifact is necessary. The estimate says how much the current assumptions retain; it does not decide which artifacts are valuable. After reviewing Total storage, compare Retained artifact jobs, Latest-successful protection, Caches, Reserve allowance, and the Retention Policy rows to see which policy setting is creating the footprint.

Step-by-Step Guide:

Use the main inputs for the rolling artifact footprint, then open Advanced when quota, growth, or reserve planning matters.

1. Enter Artifact size in MiB/build. The Storage Footprint tab should show Effective artifact size after the compression setting is applied.
2. Set Builds per day, Retention period, and Active branches or refs. Retained artifact jobs should equal those three values multiplied together.
3. Set Compression savings and Cache multiplier. Retained artifacts should move when compression changes, and Caches should move when the multiplier is above 0.
4. Choose Keep latest successful per ref. Latest-successful protection should show one effective artifact per active ref when the option is enabled and 0 when it is disabled.
5. Open Advanced for Export label, Storage quota, Monthly growth, and Reserve allowance. A positive quota enables quota percent and Quota headroom in the result.
6. Review the summary badge. Storage planned means no positive quota is near its warning point, quota watch means total storage is above 80% of quota, and over quota means the estimate exceeds the quota.
7. Open Retention Growth Curve when Monthly growth is above 0. The month-12 value should grow from both artifact size and build cadence because both are compounded.
8. If a field accepts an unexpected value, check the result rows after entry. Negative sizes and rates are treated as 0, retention and refs have a minimum of 1, and percentage fields are clamped to their supported ranges.

Interpreting Results:

Total storage is the headline estimate after retained artifacts, latest-successful protection, caches, and reserve are added. Retained artifact jobs explains why the number is large or small. If that row is high, reduce artifact-producing builds, shorten retention, remove stale refs, or stop publishing artifacts from jobs that do not need retained output.

Quota status should slow the review when a quota is entered. Over quota means the modeled total is greater than the quota. Quota watch means the modeled total is greater than 80% of the quota but not above it. Storage planned only means the modeled value did not hit those built-in quota checks; it does not prove the artifact policy is clean, secure, or cost-efficient.

False confidence often comes from setting Cache multiplier, Reserve allowance, or Storage quota to 0. Those zeros are valid when intentionally chosen, but they also remove cache demand, cleanup lag, and budget comparison from the result. Check the Artifact Mix chart and Retention Policy table before using Total storage in a cleanup ticket or quota request.

Worked Examples:

Default web application run rate. With 180 MiB artifacts, 36 builds per day, 14 days of retention, 6 active refs, 18% compression savings, a 0.25 cache multiplier, and latest-successful protection enabled, the calculator reports about 545.72 GiB in Total storage. 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.

Release project over quota. A mobile release project with 420 MiB artifacts, 18 builds per day, 30 days of retention, 9 refs, 10% compression savings, a 0.40 cache multiplier, a 15% reserve, and a 2,500 GiB quota lands near 2.82 TiB. The status becomes over quota because Total storage is about 115.7% of the quota. Shortening retention or splitting release artifacts from validation artifacts would lower the estimate faster than changing the export label.

Many refs with no latest protection. A documentation preview workflow with 85 MiB artifacts, 24 builds per day, 7 days of retention, 18 active refs, no compression savings, no caches, and Keep latest successful per ref disabled reports about 251.02 GiB. Latest-successful protection and Caches both show 0 MiB, so the result is driven by Retained artifact jobs. The main cleanup check is whether all 18 refs still need preview artifacts for a full week.

Growth forecast for a monorepo. A UI monorepo with 240 MiB artifacts, 40 builds per day, 21 days of retention, 10 refs, 20% compression savings, a 0.30 cache multiplier, 10% reserve, and 8% monthly growth starts at about 2.20 TiB. The Retention Growth Curve reaches about 13.95 TiB by month 12 because artifact size and build cadence both compound. That is a quota-timing warning even when month-zero status still reads storage planned.

Troubleshooting a surprisingly large total. If a run with 300 MiB artifacts, 20 builds per day, 30 days, 25 refs, a 0.50 cache multiplier, 20% reserve, latest-successful protection, and a 5,000 GiB quota returns about 7.73 TiB, the warning set is doing useful work. It reports over quota, flags many active refs with keep-latest behavior, and flags a high retained build count of 15,000. The first corrective path is to check stale refs and artifact-producing jobs before raising quota.

FAQ:

Glossary:

Artifact

A retained file or archive produced by a build, test, package, or release job.

Retention window

The number of days artifacts remain stored before normal expiry or cleanup.

Active ref

A branch, tag, or pipeline ref that produces and retains its own artifacts.

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:

• Store and share data with workflow artifacts, GitHub Docs.
• GitHub Actions billing, GitHub Docs.
• Job artifacts, GitLab Docs.
• Retention policies for Azure Pipelines, Microsoft Learn.
• Persisting data overview, CircleCI Docs.