Container registry cleanup is safest when it removes genuinely disposable artifacts rather than simply deleting the oldest images. This guide explains how to build a container registry retention policy for Docker Hub, GitHub Container Registry (GHCR), Amazon Elastic Container Registry (ECR), and Harbor, with a provider comparison, monitoring checklist, review cadence, and a dry-run workflow that protects production and rollback releases.
Overview
A registry retention policy defines which container images remain available, which may be deleted, and how long the organization keeps them. The goal is not to make every repository small. It is to control storage growth while preserving images that are needed for deployments, incident response, audits, testing, or rollback.
The most important distinction is between a tag and an image digest. A tag such as latest, staging, or v2.4.1 is a mutable name unless the registry or workflow makes it immutable. A digest identifies a particular image manifest. Cleanup decisions should therefore consider both the tag and the digest. Deleting an apparently old tag can still affect a deployment if that tag is the only reference to a needed digest.
A practical policy usually separates artifacts into classes:
- Protected releases: production images, approved rollback versions, and images referenced by a currently supported deployment.
- Candidate releases: images from a release branch or preproduction environment that must remain available for a defined review period.
- Development artifacts: pull-request, feature-branch, and commit-based images that can usually be retained for a shorter period.
- Unreferenced artifacts: untagged manifests and layers left after retagging, failed builds, or interrupted publishing.
Retention should be designed alongside release management and deployment records. For guidance on coordinating image availability with platform upgrades, see the Kubernetes version support and upgrade planning guide. Image construction also matters: the container base image comparison can help teams assess whether smaller or more maintainable bases reduce the amount of storage and transfer involved.
What to track
Before changing a cleanup rule, record the variables that show whether the policy is working. At minimum, track storage consumption, image count, untagged artifacts, deletion failures, and the age of the oldest retained image. Also record which repositories contain production or rollback images and whether deployments reference tags, digests, or both.
| Registry | Retention and cleanup considerations | Checks before deletion |
|---|---|---|
| Docker Hub | Review repository retention features, namespace permissions, automated build outputs, and any plan-specific storage or rate limits. Do not assume that deleting a tag immediately removes every underlying layer. | Confirm protected tags, organization ownership, automated build dependencies, and whether a deleted image can be restored. |
| GHCR | Review package visibility, repository or organization ownership, package versions, access permissions, and the behavior of package cleanup tools or APIs. Treat release-linked images differently from branch and pull-request artifacts. | Check links between packages and source repositories, deployment credentials, release records, and package-level deletion permissions. |
| Amazon ECR | Use repository lifecycle rules carefully, with explicit exclusions for protected tags or tag prefixes. Confirm how rules select images and how manifest lists, untagged images, and image scanning records are handled in the relevant environment. | Test the rule against a representative repository and review the resulting candidate set before enabling expiration. |
| Harbor | Review project-level retention rules, replication, proxy-cache repositories, vulnerability-scanning data, and the separation between deleting references and reclaiming storage through garbage collection. | Confirm replication status, read-only or protected projects, robot-account use, and whether garbage collection is scheduled safely. |
Provider behavior and terminology can change, so treat this table as a planning framework rather than a substitute for the current product documentation. Record the documentation version or policy syntax used in your runbook. Important fields include repository name, digest, tags, creation time, last pull or deployment evidence where available, environment, owner, and protection status.
Tag immutability is one of the strongest controls available. Immutable release tags prevent a later push from changing what a deployment appears to reference. Even with immutability, use digests for deployment verification and keep a separate protected list for images required during rollback.
Cadence and checkpoints
A monthly review is suitable for fast-moving development repositories; a quarterly review may be enough for stable production repositories. The cadence should become more frequent when storage approaches an internal threshold, a team changes its build system, or a repository begins producing large numbers of images.
Before a cleanup run
- Export or query the candidate images without deleting anything.
- Compare candidates with active deployment manifests, rollback documentation, release records, and incident procedures.
- Exclude production tags, release tags, signed or attested artifacts, and images covered by an approved exception.
- Check whether another registry, mirror, cache, backup, or air-gapped environment depends on the image.
- Estimate the effect on storage and confirm who owns the approval.
During and after cleanup
Start with one noncritical repository or a narrowly scoped tag pattern. Keep an audit record of the rule, execution time, candidates, deletions, failures, and operator. Afterward, verify that current deployments can still pull their images, that rollback references resolve, and that storage metrics change as expected. In systems such as Harbor, deleting image references and reclaiming layers may be separate operations; schedule garbage collection only after confirming that no remaining manifest needs those layers.
A safe dry-run workflow looks like this: inventory, classify, protect, preview, approve, delete, verify, and document. If a provider does not offer a true dry-run mode, build one outside the deletion command by listing matching manifests and saving the result for review. Never use a broad command such as “delete everything older than X” until its tag, digest, repository, and exception behavior are understood.
How to interpret changes
Rising storage does not automatically mean the retention period is too long. It may indicate larger base images, duplicated layers across build pipelines, a new matrix of architectures, more frequent releases, or failed cleanup jobs. Conversely, a sudden storage drop deserves investigation if it was not planned; it may reflect accidental deletion, a failed replication target, or a change in how the registry reports layers.
Watch for these patterns:
- Many untagged images: inspect build and retagging behavior before simply increasing deletion frequency.
- Protected images growing without limit: review whether every release really needs permanent retention, or define a documented rollback window.
- Deletion errors: check permissions, manifest references, replication, and provider-specific policy constraints.
- Deployments pulling mutable tags: prioritize immutable release references before tightening cleanup.
- Rollback tests failing: pause cleanup and restore the required release set before changing the policy.
Retention is a risk decision, not only a storage decision. A shorter window may reduce cost or quota pressure but leave fewer options during an incident. A longer window improves recovery options while increasing storage, scanning, replication, and administrative overhead. Set the policy from the recovery requirement first, then optimize the disposable artifacts.
When to revisit
Revisit the policy monthly or quarterly, and immediately after a registry migration, pricing or quota change, major registry release, CI/CD redesign, architecture expansion, or production incident. Review it before deleting images during a storage emergency, because emergency rules are most likely to overlook rollback and replication dependencies.
At each review, confirm current provider limits, lifecycle-policy syntax, API behavior, tag immutability settings, garbage-collection terminology, recovery options, and permissions. Re-run the dry-run report and compare it with the previous review. If the candidate list changes substantially, require a fresh approval rather than assuming the old rule remains safe.
The practical final check is simple: identify every image needed to deploy, diagnose, or roll back supported services; protect those images by digest or an immutable release convention; then clean only the remaining candidates in a staged run. Keep the policy, exceptions, and last verification date in version control. That turns registry cleanup from an occasional destructive task into a repeatable operational control.
