> 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/overview.md).

# Lifecycle rules overview

Automate artifact retention and cleanup with policy-based lifecycle rules that cut storage costs, enforce compliance, and keep registries manageable.

Every build pipeline produces artifacts. Over weeks and months, registries accumulate thousands of versions that no one downloads, deploys, or references again. Storage costs rise, search results become noisy, and compliance audits grow harder when stale artifacts sit alongside production releases. Lifecycle rules solve this by automating what to keep and what to remove, so your registries stay lean without manual intervention.

Harness Artifacts provides two lifecycle rule types that work together: cleanup rules that delete stale artifact versions on a schedule, and retention rules that protect critical versions from any form of deletion. Lifecycle rules combine multiple criteria, support regex-based pattern filters across all package types, and automatically protect Docker images that are actively deployed through Harness CD.

## Lifecycle management benefits

Artifact registries grow silently. A team running 20 builds a day generates over 7,000 artifact versions in a year, and most are never used after the initial integration test. Without automated lifecycle management:

* **Storage costs compound**: Cloud storage is billed per gigabyte. Container images, Maven JARs, npm packages, and other artifacts add up quickly, and stale versions consume the same space as active ones.
* **Compliance becomes harder**: Regulated industries require audit-ready control over what data is retained, for how long, and when it is removed. Manual cleanup does not provide the governance trail that auditors expect.
* **Registry usability degrades**: Long artifact lists slow down searches, make it harder to find the right version, and increase the risk of deploying an outdated build.
* **Security exposure grows**: Older artifact versions may contain known vulnerabilities. Keeping them accessible increases the attack surface.

Lifecycle rules address all of these by applying consistent, repeatable policies across your registries, with a full audit trail of every action taken.

## Rule types

Harness supports two lifecycle rule types:

* **Cleanup rule**: Identifies artifact versions that match your deletion criteria and soft-deletes them on a cron schedule (daily, monthly, yearly, or custom). Deleted artifacts remain recoverable during the recovery period configured at the account level. To create one, go to [Create a cleanup rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-cleanup-rule.md).
* **Retention rule**: Protects matching artifacts from all deletion types, including cleanup rules, manual soft delete, and manual hard delete. Retention rules have no schedule; they are evaluated automatically whenever a cleanup rule runs, and they always take priority. To create one, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).

You can combine both types on the same registry. For example, a cleanup rule removes staging builds older than 30 days while a retention rule ensures `latest` and `production-*` tags are never touched.

## Lifecycle rule processing

A lifecycle rule is a reusable policy that you create at the account, organization, or project level and attach to one or more registries. Rules do nothing until you attach them to a registry.

When a cleanup rule executes on schedule, the system:

1. Fetches all registries attached to the rule.
2. Scans artifact versions in each registry against the cleanup criteria.
3. For Docker registries, queries Harness CD and marks versions that are actively deployed as **PROTECTED**.
4. Evaluates all applicable retention rules and removes protected artifacts from the candidate set.
5. Deletes remaining candidates that satisfy **all** enabled criteria.
6. Records the execution result with a complete audit trail.

{% hint style="info" %}
**Soft delete keeps artifacts recoverable**

Lifecycle rules soft-delete artifacts in registries that support recovery. Deleted artifacts remain recoverable for the recovery period set in **Default Settings** > **Artifact Registry** at the account level. To understand deletion and recovery behavior, go to [Delete an artifact](https://developer.harness.io/artifact-registry/3.0/artifacts/delete-an-artifact.md).
{% endhint %}

## Deployment-aware protection for Docker

For Docker registries, Harness adds an automatic safety net. When a cleanup rule runs, the system 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.

This protection is automatic. You do not need to configure a retention rule to keep deployed Docker images safe.

{% hint style="warning" %}
**Non-Docker artifacts are not deployment-aware**

Deployment-aware protection applies only to Docker registries. For other package types (Maven, npm, Go, and others), create a retention rule to protect critical versions. To set one up, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).
{% endhint %}

## Manage rules

To view, create, and manage lifecycle rules, go to **Artifact Registry** > **Registries Settings** > **Lifecycle Rules**. The summary cards at the top of the page show total storage saved, artifacts cleaned, and executions in the last 30 days.

![Lifecycle Rules tab showing rule names, types, criteria, run times, and status toggles](https://3872764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6p7kagx6lOgVXV11Eevj%2Fuploads%2Fgit-blob-1c635fb60a337d16aa79a713ce91218b459ff80f%2Fjune-2026-lifecycle-rules.png?alt=media)

### Enable or disable a rule

Each cleanup rule has a toggle in the rules list. Use it to pause a rule without deleting its configuration. A disabled rule retains its registry attachments but does not execute on schedule. Toggle it back on to resume scheduled executions.

{% hint style="info" %}
**Retention rules cannot be disabled**

Retention rules do not have a toggle. To stop a retention rule from protecting artifacts, delete the rule.
{% endhint %}

### Edit or delete a rule

Select the **More** icon (**⋮**) on a rule row to access **Edit**, **Delete**, and (for cleanup rules) **Dry run**. Deleting a rule removes it and all its registry attachments. Artifacts that were soft-deleted by previous executions remain recoverable for the configured recovery period.

### Filter the rules list

Use the toolbar filters to narrow the view:

* **Rule Type**: Cleanup Rule or Retention Rule.
* **Registries**: Filter by specific registry.
* **Package Types**: Filter by package format.

### Use rules from a parent scope

Lifecycle rules created at a parent scope (account or organization) can apply at child scopes (organization or project). By default, the rules list shows rules created at the current scope and parent-scope rules that are already applied. Select **Show policies from parent scope** to see parent-scope rules that are not yet applied, then attach them to registries at the current scope.

When you use a rule from a parent scope, you can only change which registries the rule applies to. Criteria, schedule, and other settings remain controlled by the parent scope. The inheritance icon in the table indicates which rules come from a parent scope.

Execution visibility follows a top-down model:

* A parent scope can view execution entries from all child scopes. Select **Show items from child scope** on the execution detail to expand the view.
* A child scope can only view entries from its own scope, even when the rule is owned by a parent scope.

## Notifications

You can receive alerts when lifecycle rule executions complete. Artifact Registry supports two notification events:

* **Lifecycle Policy Execution Completed**: Triggers when a scheduled cleanup rule finishes.
* **Lifecycle Policy Dry Run Execution Completed**: Triggers when a dry run finishes.

Configure notification rules in the Harness platform notification settings.

## Audit trail

Harness records lifecycle rule create, update, and delete operations in the platform Audit Trail. Each audit event identifies who made the change and provides the rule configuration details. Updates include configuration changes and changes to a cleanup rule's enabled state.

## Frequently asked questions

<details>

<summary>Can I pause a lifecycle rule without deleting its configuration?</summary>

Yes. Each cleanup rule has a toggle in the rules list. Disabling it keeps the rule and its registry attachments in place but stops it from executing on schedule. Retention rules have no toggle; delete the rule to stop it from protecting artifacts.

</details>

<details>

<summary>Can I preview what a rule will delete before it runs?</summary>

Yes. Select **Dry run** from a cleanup rule's row menu to see which artifact versions would be deleted, which are protected, and how much storage would be reclaimed, without making any changes. Go to [Run a dry run](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/run-a-dry-run.md).

</details>

<details>

<summary>Can a project use a lifecycle rule created at the account or organization level?</summary>

Yes. Select **Show policies from parent scope** in the rules list to see parent-scope rules not yet applied at the current scope, then attach them to registries at the current scope. You can only change which registries the rule applies to; criteria and schedule remain controlled by the parent scope.

</details>

## 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 artifacts from deletion, go to [Create a retention rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-retention-rule.md).
* To validate a rule before it runs, 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, go to [View rule executions](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/view-rule-executions.md).
* To understand lifecycle concepts in depth, go to [Lifecycle rules](https://developer.harness.io/artifact-registry/3.0/concepts/lifecycle-rules.md).

{% @harness-feedback/feedback %}
