Skip to main content
Lifecycle policies expire images in a repository. Each rule has a unique priority, a selection, and the expire action. Rules can target tagged, untagged, or any images, with tag-prefix or tag-pattern filters where supported. The selection can keep a number of recent images or expire images based on time since push or last pull. Read the current policy at GET /v1/repositories/{repository_id}/lifecycle-policy. Replace the complete rule list with PUT on the same path. Omitted rules are not retained.

​
Preview first

Call POST /v1/repositories/{repository_id}/lifecycle-policy/preview with a candidate rules array. The response identifies matching digests and tags without deleting anything. An empty request previews the installed policy. Check that release tags and manifests needed by deployments are protected before saving the rule list. A rule based on last pull uses recorded pull activity; it does not know which images a stopped instance or a future rollback may need. Keep a separate retention policy for releases you must preserve.

​
Storage reclamation

Removing a manifest and reclaiming its layers are separate steps. Layers still referenced by other images remain stored. Repository deletion protection guards deletion of the repository itself; it does not prevent lifecycle policies from expiring images. Use registry:StartLifecyclePolicyPreview to allow previews without granting permission to install or delete policies. Read, replace, and remove policies with registry:GetLifecyclePolicy, registry:PutLifecyclePolicy, and registry:DeleteLifecyclePolicy respectively.