Immutable Tags in Harbor: Stop Silent Image Overwrites in Promotion Pipelines

A release pipeline that promotes the same tag from dev to staging to prod is a supply chain accident waiting to happen. A rebuild with the same tag release-1.2.3 can silently replace the manifest in Harbor, and every deployment that resolves that tag gets a different image than what was tested. Immutable tag enforcement in Harbor makes that overwrite impossible once a tag exists, turning a mutable alias into a reproducible reference.

The problem mutable tags create

Container tags are pointers to a manifest digest. By default a registry allows a push that repoints an existing tag to a new digest. That is convenient for latest but dangerous for promotion. Immutable tag protection blocks a push that would change the digest for a protected tag. Enforcement happens at push time in the registry backend, not as a post-push audit.

The control is useful when you want reproducible deployments and an auditable promotion path: build once, tag with a content-addressable identifier, and promote the same digest through environments without the risk of a later build reusing the tag.

How the policy is scoped in Harbor

Harbor exposes immutable tag settings at project and repository level. The UI labels and granularity are version-sensitive; newer releases support per-repository overrides while older releases may only expose per-project controls.

When configured, the mode can be scoped to:

• Existing tags only: tags already present are locked, new tags remain mutable. Useful for gradual adoption.
• New tags only: tags created after enabling the policy are locked, existing tags stay mutable.
• Both: all tags in scope are immutable from the moment the policy is applied.

The setting integrates with other Harbor controls. Vulnerability scanning, retention policies, and replication can be applied consistently, and replication jobs respect immutability on the destination so a remote site will not silently accept an overwrite.

Operational shift: tags you can trust

Enabling immutability changes tagging conventions. Teams move away from mutable aliases like latest or stable and toward unique, content-addressable tags such as a git SHA or a build ID. Promotion then copies the digest rather than re-tagging.

Example configuration surface in a test project. Run the following from a CI or build host with push permissions to Harbor.

# Log in to Harbor
docker login harbor.example.com -u <harbor-username> -p <harbor-password>

# Tag and push a first build
docker tag myapp:latest harbor.example.com/myproject/myapp:v1.0.0-shaabc123
docker push harbor.example.com/myproject/myapp:v1.0.0-shaabc123

With immutable tag protection enabled for the project or repository, a subsequent push that attempts to repoint v1.0.0-shaabc123 to a different image is rejected by the registry. The push fails at the registry validation step.

To verify the setting, inspect project and repository metadata in Harbor's UI and confirm the immutable tag mode is set to existing, new, or both as intended. A practical check is to attempt a second push with the same tag but a different local image and observe that the registry rejects the overwrite.

Trade-offs and limits

Immutability prevents overwrite but does not prevent deletion. A tag can still be removed if project protection and retention policies allow it. For full lifecycle control pair immutable tags with project protection rules and retention policies.

Enabling immutability on repositories that already use mutable tags such as latest will break CI pipelines that expect to overwrite tags. The safe migration path is to start with new tags only, update pipelines to use unique tags, and later lock existing tags.

Rollback is straightforward because the policy is a configuration change. In Harbor's project settings you can change the immutable tag mode back to disabled or to a less restrictive scope. Existing tags remain at their current digests; disabling the policy only allows future overwrites.

Harbor's immutable tag enforcement is an engineering control, not a policy substitute. It makes the registry enforce the convention you want: build once, tag once, promote the digest. Combined with scanning and retention, it reduces silent drift in promotion pipelines.