Prevent Tag Overwrites with Harbor Project-Level Immutable Tags

Desired outcome

A Harbor project rejects any push that reuses an existing tag, so artifact digests cannot be silently replaced underneath a tag name such as latest or 1.0. New, previously unused tags can still be pushed.

Use this when you need artifact immutability for compliance, rollback safety, or supply-chain auditing. It does not delete existing tags and does not block creation of new unique tags.

Prerequisites

• Access to a Harbor v2.x registry as a project administrator or system administrator.
• The target project already exists.
• Docker, crane, or another OCI-compatible client installed on the machine performing the test push.
• Credentials configured for the Harbor registry, typically with docker login harbor.example.com.

crane is a command-line tool for interacting with container registries and image digests.

Enable immutable tags in the Harbor portal

1. Open the Harbor portal and sign in with an account that has project administrator or system administrator rights for the target project.
2. Select Projects, then open the target project.
3. Open Project settings or the project configuration page.
4. Find the Immutable tag setting and enable it.
5. Save the project configuration.

Enabling this setting changes project state. It applies to future pushes only; tags already present in the project remain as they were, but they can no longer be overwritten.

Enable immutable tags with the Harbor API

Automation can update the same setting through Harbor's project API. Field names and endpoint behavior vary between Harbor versions, so verify the request schema against your running Harbor version before using this in production.

PATCH /api/v2.0/projects/{project_id}
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "metadata": {
    "immutable_tag": true
  }
}

Run this from a machine with network access to the Harbor API. Replace {project_id} with the project's numeric ID and {admin_token} with a valid system administrator or project administrator token. A successful response means the setting was updated; confirm it in the portal afterward.

Update CI/CD pipelines before enabling on active projects

Workflows that repeatedly push the same mutable tag will fail immediately after immutability is enabled. Replace tag reuse with unique versioned tags or digest references.

Example build-and-push step before immutability:

docker build -t harbor.example.com/{project}/app:latest .
docker push harbor.example.com/{project}/app:latest

Example after immutability:

docker build -t harbor.example.com/{project}/app:1.4.2-20261112 .
docker push harbor.example.com/{project}/app:1.4.2-20261112

A digest reference identifies an image by content hash rather than by tag:

docker pull harbor.example.com/{project}/app@sha256:{digest}

Here {digest} is the SHA-256 content identifier for the manifest. Use digest references when deployment systems need to reference an exact artifact without relying on tag stability.

Verify enforcement

1. Open the project in the Harbor portal and confirm the Immutable tag toggle is enabled.
2. Attempt to push an image using a tag that already exists in the project:

docker push harbor.example.com/{project}/app:{existing-tag}

Run this from a CI runner or workstation authenticated to Harbor. Expect the registry to reject the push because the tag already exists. Do not rely on a specific error code; Harbor versions may report the rejection differently.

1. Push an image with a tag that has never been used in the project:

docker push harbor.example.com/{project}/app:{new-tag}

Expect this push to succeed, confirming that immutability blocks overwrites but not new tags.

1. Open Harbor Audit Logs for the project and confirm the rejected push attempt is recorded.

Limitations

• Immutability prevents tag overwrites only. It does not prevent tag deletion, repository deletion, or project deletion.
• Enabling immutability on an existing project does not retroactively alter tags already pushed.
• CI jobs that push latest or other reused tags will break until the pipeline is updated.
• Behavior and API field names can vary between Harbor versions.

Recovery: disable immutability

Because enabling this setting changes project state, you can reverse it if a pipeline cannot be updated quickly:

1. Open the target project in the Harbor portal.
2. Go to Project settings.
3. Disable Immutable tag and save.

Disabling restores the ability to overwrite existing tags. Treat this as a temporary recovery step, not a substitute for updating CI/CD to use unique tags.

Version assumptions

This guide assumes Harbor v2.x. UI paths, API endpoints, and metadata field names may differ in other versions. Confirm the exact procedure against your installed Harbor version before making production changes.