Retention policies
A retention policy is a list of rules evaluated against every tag, version and object in its scope. An artifact is kept if any rule says to keep it; otherwise it is marked for removal.
The policy file
retention.yaml
# retention.yaml
version: 2
scope: tidewater/* # glob over repository paths
protect:
digests_in_use: true # never remove a digest a registered cluster pulled in the last 30 days
tags: ["latest", "stable"]
rules:
- name: releases
match: { tag: "^v[0-9]+\\.[0-9]+\\.[0-9]+$" }
keep: forever
- name: main-builds
match: { tag: "^main-[0-9a-f]{7}$" }
keep: { last: 10 }
- name: feature-builds
match: { tag: "^(feat|fix)-" }
keep: { max_age: 21d, last_pulled_within: 7d }
- name: untagged
match: { untagged: true }
keep: { max_age: 3d }Preview and apply
terminal
$ qln retention plan retention.yaml
scope tidewater/* (212 repositories, 41,226 tags, 18.7 TB)
releases keep 2,904 tags
main-builds keep 1,970 tags, remove 22,418 tags
feature-builds keep 611 tags, remove 9,847 tags
untagged keep 88 manifests, remove 3,388 manifests
would free 9.3 TB (49.7%), 0 protected artifacts affected
$ qln retention apply retention.yaml
policy v14 active; first sweep starts at 10:00 UTCHow rules combine
- Rules do not have an order. A tag matching several rules is kept if any of them keeps it.
last: Ncounts the newest N tags per repository, or per branch withper: branchwhen branch metadata is available from the CI integration.last_pulled_withinuses the pull time of the manifest or of any layer reachable from it.- Referrers follow their subject; layers are removed only when no manifest in any repository refers to them.
Soft delete and garbage collection
Removal happens in two stages. First the tag or manifest is soft-deleted and disappears from pulls and listings. Seven days later the nightly sweep, which runs at 02:00 UTC in each storage cell, deletes blobs that nothing references and returns the space to your pool.
terminal
$ qln retention trash ls tidewater/api
TAG REMOVED BY REMOVED AT PURGES IN
main-3f9a1c2 keep-last 2026-11-03 10:02 4 d 21 h
$ qln retention restore tidewater/api:main-3f9a1c2
restored tidewater/api:main-3f9a1c2 (sha256:90b7e1...)Retention applies to cache entries and generic repositories too, with
max_age and last_pulled_within. Package repositories keep every published version by default, because removing a version can break a lockfile somewhere.