Lifecycle policies

How lifecycle rules decide which images are deleted, which are always kept, and how long a deleted image can be restored.

Last updated 18 November 2026View as Markdown

A lifecycle policy is a list of rules that delete images. The registry applies it every hour, at minute 17 (UTC).

Which policy a repository runs

Each repository is in one of three modes:

Mode What applies
inherit The organization's default (see Set the organization default)
own The repository's own policy (see Set a lifecycle policy)
none Nothing is deleted

A new repository is inherit. Until your organization saves a default, the platform's default applies: untagged images after 7 days, and images not pulled for 90 days, always keeping the newest 10 tagged images; restorable for 7 days. It is active for organizations created from 2026-11-17 on, and a preview (it deletes nothing) for older ones.

How rules decide

  • Rules are applied lowest priority first. The first rule whose selection matches an image decides it; later rules never see that image.
  • A selection is untagged, tagged (with tag patterns or prefixes; every pattern must match one of the image's tags) or any.
  • A condition is days since the push, days since the last pull (ews-lifecycle/v1 only), or "beyond the newest N" of the images the rule selected.
  • A keep clause (ews-lifecycle/v1 only) wins over every rule: the newest N tagged images, images tagged like a pattern, or the highest release of every major version.

Two formats are accepted: AWS ECR's lifecycle JSON, so an ECR policy pastes in unchanged, and ews-lifecycle/v1. The organization default accepts only ews-lifecycle/v1.

Never deleted

Whatever the rules say, these images are kept:

  • images in use: the image an app is set to deploy, the images of each app's live deployment and its last ten, a function's image, the image of a sandbox that has not ended or of a sandbox pool, and the images of CI jobs of the last 30 days;
  • an image under a legal hold;
  • the platform images of a multi-platform image that stays, and the signatures or SBOMs of an image that stays;
  • anything pushed in the last hour.

Restorable for a number of days

A deleted image is gone for every client at once: a pull answers 404. It stays restorable for softDeleteDays (0–30, 7 by default; always 7 for an AWS ECR policy), then it is purged. A repository's own policy can set 0, which deletes at once with no undo; the organization default needs at least 1. See Restore an expired image.

While an image waits to be purged, its layers count toward your bill but not toward your storage quota.

Limits

  • At most 50 rules per policy.
  • One run deletes at most 1,000 images per repository; the rest follow in the next runs.
  • A dry run lists at most 5,000 images; its totals count them all.
Did this page help you?