Retention Policy

Automatically prune images based on the number of tags within a repository. This prevents clutter from ephemeral development builds.

• Keep Last N Tags: Retain only the 10 most recently pushed images per repository.
• Untagged Image Removal: Automatically delete images that no longer have a tag reference, reclaiming orphaned storage.
• Semantic Version Filtering: Exclude images matching a regex like v[0-9]+\.[0-9]+\.[0-9]+ to protect release builds while cleaning feature branches.

Define a Time-To-Live (TTL) for images to ensure no artifact persists indefinitely. This is critical for enforcing data residency and storage quotas.

• Absolute Expiry: Delete any image older than 90 days.
• Last Pull Time: Remove images that haven't been pulled for 30 days, indicating they are no longer actively used in deployments.
• Build Timestamp Filtering: Use the OCI image creation timestamp, not the push time, to determine age for accurate lifecycle tracking.

Integrate with scanning tools like Trivy to create policies that quarantine or delete images based on their security posture. This enforces a 'clean registry' mandate.

• Critical CVE Block: Immediately delete any image with a critical vulnerability and a CVSS score above 9.0.
• Grace Period for Fixes: Allow a 7-day window to patch a high-severity vulnerability before the retention policy automatically purges the image.
• Deny-Listed Packages: Automatically remove any image containing a specific library version known to be end-of-life or internally banned.

Protect specific artifacts from automated deletion to ensure production stability and compliance with SLSA provenance requirements.

• Pinned Digest Locking: Mark images by their SHA256 digest as immutable, preventing deletion regardless of tag count or age.
• Production Namespace Exclusion: Exclude repositories in a production/ namespace from all automatic retention policies.
• Signed Image Preservation: Retain images that have a valid Cosign signature, ensuring only verified artifacts bypass the garbage collection process.

Use retention policies as a proactive mechanism to stay within the allocated storage limits of a private registry, preventing denial-of-service conditions.

• Repository-Level Caps: Set a hard limit of 500 GiB per project; when exceeded, the policy automatically purges the oldest untagged images first.
• Layer Deduplication Awareness: Policies should account for shared layers; deleting an image manifest only reclaims space when the last reference to a blob is removed.
• Warning Thresholds: Trigger alerts at 80% quota utilization before the policy executes destructive deletions, giving teams time to archive critical data.

Retention policies run on a defined schedule and must produce immutable logs for compliance and debugging.

• Dry-Run Mode: Simulate a policy execution to generate a report of which images would be deleted without actually removing them, allowing for safe policy tuning.
• Cron-Based Scheduling: Execute retention jobs during low-traffic windows (e.g., 03:00 UTC) to minimize performance impact on the registry.
• Immutable Audit Trail: Log every deletion event with the image digest, tag, policy rule triggered, and timestamp to an external syslog server for SIEM integration.

A systematic convention for assigning tags that directly determines the effectiveness of tag-count-based retention rules. Immutable tags like Git commit SHAs enable precise pruning, while mutable tags like latest or develop complicate retention logic.

• Semantic versioning (v1.2.3) allows retention policies to keep the last N minor versions
• Timestamp-based tags enable age-based cleanup without relying on push-time metadata
• Poor tagging strategies lead to retention policies accidentally deleting production images or preserving stale artifacts indefinitely

A content-addressable SHA256 hash that immutably identifies a specific image manifest. Retention policies that operate on digests rather than tags provide cryptographic assurance that the deleted artifact is exactly the one intended—no tag mutation ambiguity.

• Digest-based retention is immune to tag reassignment attacks
• Registries store digests in an immutable content-addressable storage layer
• Retention policies referencing digests can safely clean up images even when tags have been overwritten or removed

A local, read-only pull-through cache that replicates upstream images. Mirror retention policies must balance cache freshness against storage constraints—evicting rarely pulled images while preserving frequently used layers.

• Mirror retention often uses LRU (Least Recently Used) eviction based on pull frequency
• In air-gapped environments, mirror retention is critical because manual re-import is expensive
• Misconfigured mirror retention can cause deployment failures when cached images are prematurely deleted