Enable Immutable Tag Protection in Harbor Projects: A Step‑by‑Step Guide

What You’ll Achieve

The goal is simple: once an image is pushed to a Harbor project under a given tag, that tag becomes read‑only. Harbor will reject any subsequent push that attempts to overwrite the same repository:tag combination. This protects released artifacts from accidental or malicious changes while still allowing you to pull the images normally.

Prerequisites

• Harbor instance 2.8 or newer – immutability support was added in 2.8.
• Administrator or Project Administrator role on the target project.
• A project that already contains at least one repository with images.
• Knowledge of your CI/CD pipelines: if you use mutable tags like latest, you’ll need to adjust those workflows or use separate mutable projects.

Step‑by‑Step Procedure

1. Verify Harbor Version

Run a quick request against the API to confirm the version supports immutability:

curl -s -u admin:Harbor123 https://harbor.example.com/api/v2.0/version

Look for a Version field of 2.8 or higher. If it’s older, upgrade before proceeding.

2. Enable Immutable Tags via the UI

1. Log in to the Harbor web UI with an account that has Project Admin rights.
2. Navigate to Projects and click the target project.
3. Click Settings → Configuration.
4. Under Tag Management toggle Prevent Tag Override (also called Immutable Tags in some UI versions).
5. Optionally set a rule: e.g., "Immutable tags must match the pattern `v[0-9]+\.[0-9]+\.[0-9]+`". This restricts which tags become immutable.
6. Click Save. A green badge appears on the project overview indicating the policy is active.

3. Enable Immutable Tags via the API

For automation or scripting, update the project with a JSON payload:

curl -k -u admin:Harbor123 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"immutable_tag_policy":{"enabled":true,"tag_rule":"v[0-9]+\\.[0-9]+\\.[0-9]+"}}' \
  https://harbor.example.com/api/v2.0/projects/PROJECT_ID

Replace PROJECT_ID with the numeric ID of the project (find it in the URL or via GET /api/v2.0/projects?name=projname).

4. Test the Protection

1. Build a Docker image locally:

   docker build -t harbor.example.com/proj/repo:1.0.0 .
   

2. Push it:

   docker push harbor.example.com/proj/repo:1.0.0
   

3. Push the same tag again with a new image (or the same image after a minor change). The push should fail with an error similar to:

   Error response from daemon: manifest for harbor.example.com/proj/repo:1.0.0 already exists and immutability is enforced
   

4. Pull the image from another client to confirm read access is unaffected:

   docker pull harbor.example.com/proj/repo:1.0.0
   

Verification Checklist

• UI shows the immutable badge on the project page.
• API /api/v2.0/projects/PROJECT_ID returns immutable_tag_policy.enabled:true.
• Attempted re‑push results in a 409 conflict or a clear "tag overwrite denied" message.
• Audit logs contain entries for the policy toggle and for the rejected push attempt.

Recovery Options

Immutability is a safeguard, but sometimes you must correct a bad image. Harbor allows deletion of a protected image, which removes the tag from the registry. Use the following steps:

1. Disable the Policy Temporarily

1. In the UI, toggle Prevent Tag Override off and Save.
2. Alternatively, patch the project to set enabled:false.

2. Delete the Bad Image

Use the UI: Project → Repository → repo → 1.0.0 → Delete. Or via API:

curl -k -u admin:Harbor123 -X DELETE \
  https://harbor.example.com/api/v2.0/projects/PROJECT_ID/repositories/repo/artifacts/ARTIFACT_ID

Replace ARTIFACT_ID with the numeric ID returned by GET /api/v2.0/projects/PROJECT_ID/repositories/repo/artifacts.

3. Re‑enable the Policy

Re‑activate the immutable tag setting via UI or API as described earlier.

Engineering Decision Note

Apply immutability only to projects that host production releases. Keep a separate project for CI pipelines that use mutable tags such as latest or dev. This keeps the safety net without breaking build workflows.

Limitations & Risks

• Older Harbor releases (pre‑2.8) do not enforce immutability; verify your version.
• Admin accounts can still delete images, so restrict admin access and monitor audit logs.
• Replication and garbage collection may leave stale references if immutability is toggled frequently; schedule changes during maintenance windows.
• Changing the immutable tag rule after images exist does not retroactively protect older tags.

Conclusion

By enabling immutable tags you add a robust layer of protection to your released container images. The UI and API steps are straightforward, and the verification checks give you confidence that Harbor is enforcing the policy. Remember to plan where mutable tags are still needed and to keep admin privileges tight to preserve the integrity of your registry.