Tag Retention & Immutability Rules

Relevant source files

The following files were used as context for generating this wiki page:

• api/v2.0/swagger.yaml
• src/pkg/retention/policy/models.go
• src/pkg/immutable/match/rule/match_test.go
• src/portal/src/app/base/project/tag-feature-integration/immutable-tag/immutable-tag.component.ts
• src/portal/src/app/base/project/tag-feature-integration/immutable-tag/add-rule/add-immutable-rule.component.ts
• tests/apitests/python/test_tag_immutability.py
• src/server/middleware/immutable/pushmf_test.go

Tag Retention and Immutability Rules are critical governance features in Harbor that manage the lifecycle and integrity of artifacts. Tag Retention allows administrators to define policies that automatically clean up old or unused artifacts based on specific criteria like age, pull count, or push time. Tag Immutability ensures that specific tags cannot be overwritten or deleted, preventing accidental or malicious changes to production-ready images.

These features are scoped at the project level, allowing tailored management strategies for different environments (e.g., development vs. production). They utilize selectors and filters to target specific repositories and tags within a project.

Sources: api/v2.0/swagger.yaml, src/pkg/retention/policy/models.go:19-48, src/portal/src/app/base/project/tag-feature-integration/immutable-tag/immutable-tag.component.ts:33-55

Tag Retention Policies

Tag Retention is driven by policies consisting of multiple rules. Each policy defines how artifacts are evaluated for preservation or deletion. Policies can be triggered manually or via a scheduled cron job.

Policy Architecture

A Retention Policy includes an algorithm (currently "OR"), a collection of rules, a trigger mechanism, and a scope defining which project the policy applies to.

Retention Rule Templates

Rules are built from predefined templates that determine the retention logic.

Template ID	Description	Parameters
nDaysSinceLastPush	Retain artifacts pushed within the last N days	days (int)
latestPushedK	Retain the most recent K pushed artifacts	count (int)
latestPulledK	Retain the most recent K pulled artifacts	count (int)
nDaysSinceLastPull	Retain artifacts pulled within the last N days	days (int)
always	Always retain matching artifacts	None

Sources: src/pkg/retention/policy/models.go:121-155, api/v2.0/swagger.yaml:definitions/RetentionRuleMetadata

Tag Immutability Rules

Immutability rules prevent specific tags from being modified (pushed again) or deleted once they match the rule criteria. Unlike retention, which is a cleanup task, immutability is enforced during API requests via middleware.

Enforcement Logic

When a push or delete request is made, Harbor checks if the target artifact matches any active immutability rules. If a match is found, the operation is blocked with a 412 Precondition Failed status code.

Rule Selection & Matching

Immutability rules use "doublestar" pattern matching for both repositories and tags.

Selector Type	Decoration	Example Pattern
Repository	repoMatches / repoExcludes	library/**, {image_a,image_b}
Tag	matches / excludes	release-**, v1.*

Sources: src/pkg/immutable/match/rule/match_test.go:39-75, src/portal/src/app/base/project/tag-feature-integration/immutable-tag/add-rule/add-immutable-rule.component.ts:182-198

Data Flow & Components

The system interacts across the Portal (UI), API Server, and Controller layers.

Policy Execution Flow

The following sequence diagram illustrates the lifecycle of a retention execution, from creation to task logging.

Configuration and Management

API Endpoints

The following endpoints manage the lifecycle of these rules:

Endpoint	Method	Description
/projects/{project_id}/immutabletagrules	GET/POST	List or create immutability rules
/retentions	POST	Create a new retention policy
/retentions/{id}/executions	POST	Manually trigger a retention run (supports dry_run)
/retentions/{id}/executions/{eid}/tasks	GET	View detailed tasks and counts for an execution

Sources: api/v2.0/swagger.yaml:paths//projects/{project_name_or_id}/immutabletagrules, api/v2.0/swagger.yaml:paths//retentions/{id}/executions

Rule State Management

Rules can be enabled or disabled without being deleted. This is useful for temporary bypasses during maintenance. In the UI, this is managed via the toggleDisable function which updates the disabled boolean in the rule metadata.
Sources: src/portal/src/app/base/project/tag-feature-integration/immutable-tag/immutable-tag.component.ts:83-104

Summary

Tag Retention and Immutability provide essential governance for container projects. Retention automates storage optimization by removing artifacts that no longer meet business needs (e.g., stale dev builds), while Immutability safeguards the software supply chain by locking production tags against modification. Both systems leverage a flexible selector framework allowing for precise targeting of resources.