Lifecycle rules
Understand how lifecycle rules automate artifact cleanup and retention so registries stay lean and critical versions stay protected.
Every CI pipeline that runs pushes a new artifact version. A busy team running dozens of builds a day can accumulate thousands of image tags or package versions within weeks, and the vast majority of them are never used again. Storage costs grow quietly in the background, and finding the right version becomes harder as the list grows longer.
Lifecycle rules solve this by automating the decision of what to keep and what to remove, on a schedule you define, without requiring anyone to remember to do it manually.
What lifecycle rules are
A lifecycle rule is a reusable policy that you attach to one or more registries. At the scheduled time, Harness evaluates every artifact version in those registries against the rule's criteria and soft-deletes the versions that match.
Two rule types work together:
Cleanup rule: Identifies artifact versions that match your deletion criteria and soft-deletes them on a cron schedule (daily, monthly, or custom).
Retention rule: Permanently protects matching versions from deletion, whether by a cleanup rule, a manual soft delete, or a manual hard delete. Retention rules are always evaluated first and always win.
You can combine both types on the same registry. A cleanup rule removes stale snapshot builds; a retention rule ensures your latest and production-* tags are never touched.
How cleanup criteria work
A cleanup rule can use up to three criteria:
Keep last N versions: Retains the N most recently uploaded versions of each package, ordered by upload timestamp, not by semantic version. Version
2.0.0uploaded before1.9.9is older in Harness terms, even if it is numerically higher.Older than X days: Deletes versions whose upload timestamp is beyond the threshold.
Not downloaded in X days: Deletes versions with no download activity in the window.
When you enable more than one criterion, all conditions must be true before a version is deleted. Enabling "older than 90 days" and "not downloaded in 30 days" means a version must be both older than 90 days and unused for 30 days; a version that is old but still being downloaded is kept.
Soft delete and recovery
Lifecycle rules never hard-delete artifacts. When a version is deleted, it enters a recovery period configured at the account level in Default Settings. During that window, the version remains visible in the soft-deleted state and can be restored. After the recovery period expires, the version is permanently removed.
This means a misconfigured rule does not cause immediate, irreversible loss. You can detect the problem during the recovery window and restore affected versions.
Deployment-aware protection for Docker
For Docker registries, Harness adds an automatic safety net. When a cleanup rule runs, Harness queries Harness CD and marks every Docker image version that is actively deployed in any environment as PROTECTED. Those versions are skipped regardless of whether they match the cleanup criteria and regardless of whether a retention rule covers them.
This protection is automatic; no retention rule is required to keep deployed images safe. It applies only to Docker registries; for other package types, use retention rules to protect critical versions.
Scoping and pattern filters
Rules are created at the account, organization, or project level and attached to specific registries or to All Registries, a dynamic selection that automatically includes registries created after the rule.
Pattern filters let you narrow a rule to specific packages or version patterns using regular expressions. For example, a Maven cleanup rule with the version pattern .*-SNAPSHOT only evaluates SNAPSHOT versions; release versions are never candidates. A Docker cleanup rule with the tag pattern staging-.* only evaluates staging tags, leaving production tags untouched.
Dry running before activating
Before a cleanup rule runs for the first time on a production registry, use Dry run from the rule actions menu. A dry run evaluates the rule with identical logic but makes no changes. The result shows which versions would be deleted, which are protected, and how much storage would be reclaimed. Run dry runs whenever you change the criteria or attach new registries.
Use cases
Keep the 10 most recent Docker builds, delete everything older than 90 days
A platform team builds a microservice dozens of times a day. They set a cleanup rule with "keep last 10 versions" and "older than 90 days". Only builds outside the top 10 that are also more than 90 days old are deleted. The most recent 10 versions of every tag are always safe.
Delete unused Maven SNAPSHOT versions
A Java team uses SNAPSHOT builds for integration testing. They configure a cleanup rule targeting version pattern .*-SNAPSHOT with "not downloaded in 30 days". SNAPSHOT builds that have not been pulled in a month are removed automatically, keeping the registry lean without touching release versions.
Protect latest and production tags unconditionally
A cleanup rule sweeps staging tags. A retention rule with tag patterns latest and production-.* ensures those versions survive regardless of age or download history. Even an account-wide cleanup rule cannot touch them.
Next steps
To automate artifact deletion, go to Create a cleanup rule.
To protect critical versions, go to Create a retention rule.
To preview changes safely, go to Run a dry run.
Last updated
Was this helpful?