retention

The retention section controls what imglife cleanup deletes.

Structure

retention:
  keep_last: 5
  max_age_days: 90
  exclude_tags:
    - latest
    - stable

  archive:
    enabled: true
    registry: registry.example.com/archive
    keep_days: 180

Fields

Field	Type	Required	Default	Description
keep_last	integer	no	5	Number of most-recent tags to keep per image
max_age_days	integer	no	30	Maximum age in days; older tags are deleted
exclude_tags	[]string	no	[]	Tags to never delete (exact match)
archive.enabled	bool	no	false	Move expired tags to an archive registry before deletion
archive.registry	string	if archive	—	Registry path for archived images
archive.keep_days	integer	no	90	Days to retain archived tags before final deletion

How the policy works

For each configured image, imglife cleanup:

1. Fetches the full tag list from the OCI registry.
2. Sorts tags by creation date (newest first).
3. Excludes any tags matching exclude_tags.
4. Keeps the keep_last most recent tags.
5. Deletes (or archives) tags older than max_age_days.

Both conditions apply: a tag must violate either the keep_last limit or the max_age_days limit to be a deletion candidate. A tag at position 6 that was created 10 days ago is deleted because keep_last=5; a tag from 120 days ago is deleted regardless of position.

Steps 2 and 4 are performed per version line — one line per sync entry targeting the repository (with its own keep_last) and one per build.images block producing it — so an older line is never evicted by a newer one sharing the same repository. Tags matching no line of a mirror repository stay ranked together under retention.keep_last. A base tag whose line was removed from the config becomes a type-orphan and is deleted after max_age_days.

Archiving

When archive.enabled: true, imglife copies the tag to the archive registry before deleting it from the source:

registry.example.com/bases/alpine:3.19.4-core1.0.0
  → copy → registry.example.com/archive/bases/alpine:3.19.4-core1.0.0
  → delete from source

After archive.keep_days days, subsequent cleanup runs delete the archived tag too.

Orphan detection

imglife also detects type-orphan images: images that exist in the registry but are no longer declared in the build: section. These are reported in the --list output but not automatically deleted — manual confirmation is required.

Preview and dry-run

Always preview before applying:

imglife cleanup --list    # show what would be affected
imglife cleanup --dry-run # simulate without deleting
imglife cleanup           # apply