Skip to content
Start free
Documentation menu

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 UTC

How rules combine

  • Rules do not have an order. A tag matching several rules is kept if any of them keeps it.
  • last: N counts the newest N tags per repository, or per branch with per: branch when branch metadata is available from the CI integration.
  • last_pulled_within uses 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.