Retention

Read this before your storage fills up, not after.

The problem

Push three different builds to :latest and you have pushed three images. The tag points at the third. The first two are untagged — nothing references them by name, they are invisible in most registry UIs, and on most registries they are stored and billed forever.

On a retag-heavy workflow, which is the normal one, storage only ever grows. A repository showing 38 MB of tagged images can easily be holding 470 MB.

What we do differently

Two things:

We show you the real number. Every repository reports both its tagged size and its total size, including untagged manifests. The project total always reconciles with the sum of its repositories, so there is never an unexplained gap between the number on the invoice and the number in the UI.

Untagged images are reclaimable. A retention rule expires them on a schedule you set, and garbage collection frees the underlying layers once nothing else references them.

Setting a rule

On a repository or a project, set:

• Keep the last N tagged images. Older tagged images beyond N are unlinked. Default is to keep everything; there is no automatic deletion of tagged images unless you ask for it.
• Expire untagged after a period. Untagged manifests older than the window are unlinked. Seven days is a sensible default — long enough to roll back to yesterday's build, short enough that the retag churn does not accumulate.

Nothing is deleted the instant a rule matches. Unlinked manifests pass through a grace period before garbage collection frees the bytes, so a rule set carelessly can be corrected before it costs you anything.

What is safe

• Layers are shared. Reclaiming an image frees only the layers no remaining image references. A base layer used by fifty images survives until the last one goes.
• Digest pulls keep working until collection. An image unlinked by a rule is still pullable by digest during the grace period.
• Tags are never removed by the untagged rule. By definition it only touches manifests that no tag points at.

Recommended settings

Checking before you commit

The panel shows what a rule would reclaim before you enable it. Look at the number, then turn it on.