> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle policies

> Preview and automate image cleanup by tag state, age, or count.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.