Build output policy sizing

CI Artifact Retention Planner

Estimate a steady rolling artifact footprint and find the retention duration that fits a quota after other usage and reserve.

Decision guide

Convert producing runs into an explicit retention budget

What this tool helps you decide

This planner estimates the steady storage used by one class of continuous-integration artifact and tests a requested retention period against a user-entered quota. It answers how many days of outputs the measured production rate can retain after reserving free quota and subtracting other known usage. Use it for test bundles, installers, coverage archives, compiled packages, debug symbols, logs intentionally uploaded as artifacts, or other job outputs that must remain downloadable after the runner workspace is cleaned.

Before you start

Measure the stored size of the actual uploaded artifact after archive compression. Count producing runs across pull requests, branches, tags, scheduled jobs, release matrices, retries, and platforms, but exclude jobs that never upload this artifact class. Record the requested days from rollback, debugging, audit, or release-support needs. Copy the current quota and other usage from the platform report. If protected releases use a different retention rule, calculate them separately instead of averaging unlike policies.

How the calculation works

Daily artifact ingest equals stored artifact size multiplied by producing runs per day. At steady state, rolling artifact storage equals daily ingest multiplied by retention days. The usable quota first applies the selected reserve, then subtracts other usage in the same accounting pool. Headroom is usable quota minus the rolling artifact footprint. Maximum modeled retention divides usable quota by daily ingest and rounds downward to a whole day. Daily expirations equal daily ingest once the policy reaches steady state.

How to interpret the results

A positive result means the selected artifact class fits under the entered assumptions; it does not prove every artifact will remain available. A negative headroom result quantifies the policy shortfall. The maximum days value is a capacity boundary, not an automatic recommendation: required release artifacts may need longer retention, while ephemeral branch outputs may need less. If current usage already includes some of the modeled class, avoid counting it again in the “other usage” field.

Worked example

An artifact stored at 1.2 GB and uploaded by 18 runs per day adds 21.6 GB daily. Fourteen-day retention creates a rolling 302.4 GB artifact store. A 500 GB quota with 15% reserved leaves 425 GB before other usage; subtracting 40 GB leaves 385 GB for this class. The policy fits with 82.6 GB of headroom, and the modeled maximum retention is 17 whole days at the same production rate.

Assumptions and limitations

The calculation assumes stable size and cadence, immediate expiry, and one accounting pool. It does not model delayed deletion, failed uploads, rerun deduplication, variable compression, minimum billing increments, download bandwidth, branch-specific policy, legal preservation, release promotion, or provider-specific quota refresh timing. Some platforms count caches and artifacts separately while others display shared totals. Use the current platform documentation and observed post-expiry usage to confirm reclamation.

Next steps

Separate release, main-branch, pull-request, and scheduled artifacts when they have different value. Reduce output contents before shortening a required rollback window, and stop uploading files already available from a package or image registry. After changing policy, wait through a complete retention cycle and compare actual usage with the model. Use the Build Cache Capacity & Churn Planner for reusable job inputs and the Container Registry Retention Planner for deployable image layers.