> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/concepts/lifecycle-rules.md).

# Lifecycle rules

Understand how lifecycle rules automate artifact cleanup and retention so registries stay lean and critical versions stay protected.

Lifecycle rules automate the decision of what to keep and what to remove from a registry, on a schedule you define, so a team running frequent builds does not have to manually prune image tags or package versions that are never used again.

## What are lifecycle rules?

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.

| Property                         | Cleanup rule                                   | Retention rule                                    |
| -------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
| Purpose                          | Deletes matching versions                      | Protects matching versions                        |
| Evaluation order                 | Second                                         | First (always wins)                               |
| Effect on deployed Docker images | Skips actively deployed versions automatically | N/A (deployment check handles this)               |
| Manual override                  | Soft-delete recovery window applies            | Cannot be overridden by any rule or manual delete |
| Schedule                         | Cron-based (daily, monthly, or custom)         | Permanent protection, no schedule                 |

## How do 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.0` uploaded before `1.9.9` is 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](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-cleanup-rule.md).
* To protect critical versions, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).
* To preview changes safely, go to [Run a dry run](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/run-a-dry-run.md).

{% @harness-feedback/feedback %}
