> 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-retention-rule.md).

# Create a retention rule

Create a lifecycle retention rule to protect critical artifacts from cleanup rules, manual soft delete, and manual hard delete.

A retention rule protects matching artifacts from all deletion types. Any version that matches a retention rule cannot be removed by a cleanup rule, a manual soft delete, or a manual hard delete. Retention rules always take priority over cleanup rules.

Use retention rules to safeguard versions that must never be deleted, such as production releases, compliance-audited builds, or golden images shared across teams.

{% hint style="warning" %}
**Protection applies to all deletion types**

Any artifact that matches a retention rule cannot be deleted by any method. To delete a protected artifact, you must first delete the retention rule that protects it.
{% endhint %}

## 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 **Retention Rule**.
6. Select **Next**.

## Configure scope and filters

This step defines which registries and artifacts the rule protects. Retention rules do not have cleanup criteria or a schedule because they are evaluated automatically whenever a cleanup rule runs against the same registries.

### Registry scope

Select which registries the rule protects:

* **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 to narrow the protection scope.

### Pattern filters

Optionally restrict which packages and versions are protected. The rule protects only 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 protection patterns:

| Pattern          | Regular expression |
| ---------------- | ------------------ |
| `latest` tag     | `latest`           |
| Production tags  | `production-.*`    |
| Release versions | `\d+\.\d+\.\d+`    |
| Specific prefix  | `release-.*`       |

Select **Submit** to create the retention rule.

## How retention evaluation works

Retention rules do not execute on their own schedule. They are enforced in two ways:

**During a cleanup run**, the evaluation flow is:

1. The cleanup rule identifies deletion candidates based on its criteria.
2. For Docker registries, Harness queries CD and marks actively deployed versions as **PROTECTED**. This step does not involve any retention rule.
3. The system checks all applicable retention rules against the remaining candidates.
4. Any version that matches a retention rule is removed from the deletion set and marked **PROTECTED**.

**Outside a cleanup run**, retention protection is enforced at the platform level. When you attempt a manual soft delete or manual hard delete on a version that matches a retention rule, Harness blocks the operation. You do not need a cleanup rule to be active for this protection to apply.

A version protected by a retention rule displays a **Protected** status badge. Hover over the badge to see which rule is protecting the artifact.

## Rule examples

**Protect `latest` and production tags**

Add these tag patterns to a retention rule on a Docker registry:

* `latest`
* `production-.*`

Any version matching either pattern is protected from cleanup rules, manual soft delete, and manual hard delete.

**Protect release versions while cleaning snapshots**

Use two rules together:

1. Create a cleanup rule with the version pattern `.*-SNAPSHOT` and a "not downloaded in 30 days" criterion. To set up the cleanup rule, go to [Create a cleanup rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-cleanup-rule.md).
2. Create a retention rule with the version pattern `\d+\.\d+\.\d+` to protect semantic-versioned releases.

The cleanup rule removes only stale snapshots. All release versions remain safe.

**Protect artifacts across the organization**

Create a retention rule at the account scope and apply it to **All Registries**. Every registry in the account, including registries created in the future, is covered. Project-level cleanup rules cannot override this protection. Child scopes can view the rule by selecting **Show policies from parent scope** on the **Lifecycle Rules** tab.

## Next steps

* To set up automated deletion, go to [Create a cleanup rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-cleanup-rule.md).
* To validate how retention and cleanup interact, go to [Run a dry run](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/run-a-dry-run.md).
* To review past executions and see which versions were protected, go to [View rule executions](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/view-rule-executions.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 %}
