Container Registry Garbage Collection and Retention Policies
Automating garbage collection in OCI registries, understanding soft-deletes vs hard-deletes, layer blob pruning, and setting automated retention rules in Harbor and Docker Hub.
Published on • November 18, 2026
AI Assistant

When you delete an image tag from a container registry (using docker image rm via API or Web console), the registry performs a Soft Delete. It removes the tag reference pointer, but the underlying filesystem layers and manifest blobs remain on storage disk!
Without active Garbage Collection (GC) and automated retention policies, private registries will continuously consume storage space until disk or cloud storage budgets are completely exhausted.
In this tutorial, we will explain how registry garbage collection works, how to run manual and automated GC on open-source registries (registry:2), and how to set retention policies in enterprise registries like Harbor and Docker Hub.
Soft Delete vs Hard Delete (Garbage Collection)
+-----------------------------------------------------------------------------------+
| 1. Soft Delete (API / Tag Removal) |
| - Removes tag pointer (e.g., deletes `repositories/app/_manifests/tags/v1`) |
| - Fast execution; layer blobs in `blobs/sha256/` remain untouched on disk! |
+-----------------------------------------------------------------------------------+
| 2. Hard Delete (Garbage Collection Execution) |
| - Scans all remaining active tag pointers across ALL repositories. |
| - Identifies orphaned layer blobs in `blobs/sha256/` not referenced by ANY tag|
| - Deletes orphaned blobs permanently from physical disk / S3 bucket. |
+-----------------------------------------------------------------------------------+
Running Garbage Collection on Official registry:2
The official registry image includes a built-in executable (registry garbage-collect) to perform hard deletions.
Step 1: Dry-Run Inspection
Always run garbage collection in dry-run mode first to see which unreferenced blobs will be removed:
docker exec -it private-registry registry garbage-collect --dry-run /etc/docker/registry/config.yml
Sample output:
myorg/myapp: mark manifest sha256:a91b2c...
sha256:4c0f3f... in use
sha256:7f8a91... in use
3 blobs marked, 12 blobs eligible for deletion
blob sha256:82b4a1... would be deleted
blob sha256:91c5d0... would be deleted
Step 2: Executing Real Garbage Collection
docker exec -it private-registry registry garbage-collect /etc/docker/registry/config.yml
Crucial Safety Warning: Read-Only Mode During GC!
If a user pushes a new image while registry garbage-collect is executing, the GC scanner might mark a newly uploaded layer blob as “unreferenced” and delete it while the upload is still in progress, corrupting the new image!
Best Practice: Put the registry in read-only mode before running GC:
# In config.yml before running GC:
storage:
maintenance:
readonly:
enabled: true
Or set the environment variable -e REGISTRY_STORAGE_MAINTENANCE_READONLY_ENABLED=true during GC windows.
Automating Registry Garbage Collection
Create a nightly maintenance script /opt/scripts/registry-gc.sh:
#!/usr/bin/env bash
set -euo pipefail
REGISTRY_CONTAINER="private-registry"
echo "[$(date)] Starting Registry Maintenance..."
# 1. Enable Read-Only mode
docker exec "$REGISTRY_CONTAINER" sh -c "echo 'storage: {maintenance: {readonly: {enabled: true}}}' >> /etc/docker/registry/config.yml"
# 2. Execute Garbage Collection
docker exec "$REGISTRY_CONTAINER" registry garbage-collect /etc/docker/registry/config.yml
# 3. Disable Read-Only mode & reload
docker restart "$REGISTRY_CONTAINER"
echo "[$(date)] Registry Garbage Collection Completed!"
Make it executable and add it to cron:
chmod +x /opt/scripts/registry-gc.sh
Setting Automated Retention Policies in Enterprise Registries
Enterprise registries like Project Harbor and Docker Hub include built-in declarative retention policy engines that automatically soft-delete stale tags before GC runs.
+-----------------------------------------------------------------------------------+
| Example Harbor Tag Retention Rules: |
| - Rule 1: Always retain the last 5 pushed tags per repository. |
| - Rule 2: Retain tags pulled within the last 30 days. |
| - Rule 3: Always retain tags matching pattern `v*.*.*` (semver releases). |
| - Purge Rule: Delete all PR preview tags (`pr-*`) older than 7 days. |
+-----------------------------------------------------------------------------------+
Configuring Retention Policies in Harbor:
- Log in to Harbor Console -> Select Project -> Tag Retention.
- Add Rule:
Retain the most recently pushed 10 artifacts. - Add Rule:
Retain artifacts matching tag pattern v*. - Schedule Cron: Run Tag Retention & Garbage Collection every Sunday at 02:00 AM.
Summary Checklist
| Action | Best Practice |
|---|---|
| Soft Delete | Use API or UI to remove stale tags regularly. |
| Garbage Collect | Run registry garbage-collect to delete orphaned layer blobs. |
| Read-Only Mode | Always set registry to read-only during GC execution. |
| Retention Rules | Automate cleanup by keeping N recent tags and semver release patterns. |
Implementing structured retention policies and automated garbage collection keeps your container registry clean, efficient, and cost-effective.