> 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/lifecycle-management/create-a-cleanup-rule.md).

# Create a cleanup rule

Create a lifecycle cleanup rule to automatically delete stale artifact versions on a schedule. Actively deployed Docker images stay protected.

A cleanup rule identifies artifact versions that match your deletion criteria and removes them on a recurring schedule. This keeps registries lean and storage costs predictable without requiring manual intervention.

Artifacts in registries that support soft deletion remain recoverable during the configured recovery period. For Docker registries, the rule is deployment-aware: each execution queries Harness CD and marks actively deployed versions as **PROTECTED**, skipping them automatically.

## Before you begin

* **Artifact Registry access**: Project Admin or Artifact Registry Administrator role. To configure roles, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* **At least one registry**: An existing registry to attach the rule to. To create one, go to [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md).

## Name the rule

1. Go to **Artifact Registry** > **Registries Settings** > **Lifecycle Rules**.
2. Select **+ New Lifecycle Rule**.
3. Enter a **Name** for the rule.
4. Add a **Description** (optional).
5. Under **Target**, select **Cleanup Rule**.
6. Select **Next**.

## Configure scope and criteria

This step defines which registries and artifacts the rule targets, and what conditions trigger deletion.

### Registry scope

Select which registries the rule applies to. Choose one of the following:

* **All Registries**: Applies to every registry under the current scope. This selection is dynamic and automatically includes registries created after the rule.
* **Specific Registries**: Select individual registries from the dropdown. Selected registries appear as tags in the field.

### Package type

Select **All Package Types** or choose a specific format (Docker, Maven, npm, and others) to narrow the rule to a single package type.

### Pattern filters

Optionally restrict which packages and versions the rule evaluates. The rule applies only to artifacts that match these patterns. **Package Name Patterns** and **Version Patterns** accept regular expressions. Type a pattern and press **Enter** to add it.

{% hint style="info" %}
**Pattern filter fields change by package type**

Docker uses name and tag patterns. Maven uses group ID, artifact name, and version patterns. Other package types use name and version patterns. Use `.*` in place of `*` to match any characters. Escape a literal `.` as `\.`.
{% endhint %}

The following examples show common patterns and their regular expression equivalents:

| Pattern      | Regular expression |
| ------------ | ------------------ |
| `prod-*`     | `prod-.*`          |
| `*-prod-*`   | `.*-prod-.*`       |
| `*prod*`     | `.*prod.*`         |
| `frontend-*` | `frontend-.*`      |
| `*-service`  | `.*-service`       |
| `1.0.*`      | `1\.0\..*`         |
| `*-SNAPSHOT` | `.*-SNAPSHOT`      |

### Cleanup criteria

You must enable at least one criterion. When you enable more than one, **all** conditions must be true for a version to be deleted (AND logic).

* **Keep last N versions**: Retains the N most recently uploaded versions of each package, ordered by upload timestamp, not by semantic version. Versions beyond this count become deletion candidates.
* **Delete artifacts older than X days**: Targets versions whose upload timestamp is beyond the specified number of days.
* **Delete if not downloaded in last X days**: Targets versions with no download activity within the specified window.

{% hint style="info" %}
**Criteria use AND logic, not OR**

Enabling "keep last 10 versions" and "older than 30 days" means a version is deleted only when it is beyond the 10 most recent uploads **and** older than 30 days. A version uploaded in the last 30 days stays even when the package has more than 10 versions.
{% endhint %}

{% hint style="info" %}
**Deployed Docker images stay protected**

On Docker registries, any version that Harness CD reports as actively deployed is marked **PROTECTED** and skipped, regardless of whether it matches the cleanup criteria. This is automatic when lifecycle rules are enabled. You do not need a retention rule for this protection.
{% endhint %}

Select **Next**.

## Set the schedule

Define when the rule executes:

1. Select a **Timezone** from the dropdown (default: UTC).
2. Choose a frequency tab:
   * **Daily**: Set the hour, minute, and AM/PM.
   * **Monthly**: Select the day of the month and time.
   * **Yearly**: Select the month, day, and time.
   * **Custom**: Enter a cron expression directly.
3. Review the generated **Cron Expression** that appears under the time picker to confirm the schedule.
4. Select **Submit** to create the cleanup rule.

The rule appears on the **Lifecycle Rules** tab with its criteria summary, last run time, and next scheduled run.

{% hint style="warning" %}
**Run a dry run before the first scheduled execution**

A dry run shows exactly which artifacts would be deleted without making any changes. To validate the rule before it runs on production data, go to [Run a dry run](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/run-a-dry-run.md).
{% endhint %}

## Rule examples

The following examples illustrate common cleanup setups. To understand the regular expressions used here, Go to [Pattern filter fields](#pattern-filters).

**Keep the last 10 uploaded versions, and delete versions older than 90 days**

Enable both criteria:

* **Keep last N versions**: 10
* **Delete artifacts older than X days**: 90

Both must be true before deletion. Harness keeps the 10 most recently uploaded versions of each package, in upload order. A version outside those 10 is deleted only when it is also older than 90 days.

**Delete unused Maven SNAPSHOT versions**

The following example configures a cleanup rule for Maven with these settings:

* **Version Patterns**: `.*-SNAPSHOT`
* **Delete if not downloaded in last X days**: 30

The rule evaluates only SNAPSHOT versions. Release versions are never candidates. A matching version is deleted when it has not been downloaded in 30 days.

**Delete staging tags from a Docker registry**

The following example creates a cleanup rule with these settings:

* **Tag Patterns**: `staging-.*`
* **Delete artifacts older than X days**: 14

Only Docker tags matching `staging-*` are evaluated. Production and `latest` tags are not candidates. To protect production tags explicitly, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).

## Next steps

* To protect specific artifacts from cleanup, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).
* To validate which artifacts a rule targets, go to [Run a dry run](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/run-a-dry-run.md).
* To review past cleanup executions, go to [View rule executions](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/view-rule-executions.md).
* For lifecycle concepts and additional examples, go to [Lifecycle rules](https://developer.harness.io/artifact-registry/3.0/concepts/lifecycle-rules.md).
* For all available fields and allowed values, go to [Lifecycle rule fields](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/lifecycle-rule-fields.md).

{% @harness-feedback/feedback %}
