---
title: "Tag Immutability"
date: 2021-08-13
lastmod: 2026-05-29
canonical: "https://container-registry.com/docs/user-manual/images/tags/tag-immutability/"
source: "https://container-registry.com/docs/user-manual/images/tags/tag-immutability/index.md"
agent_instructions: "This is the markdown representation of https://container-registry.com/docs/user-manual/images/tags/tag-immutability/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt."
---

> Agent-friendly representation of <https://container-registry.com/docs/user-manual/images/tags/tag-immutability/index.md>. Site index: <https://container-registry.com/llms.txt>.


# Tag Immutability


Tag Immutability
=================================

## What Is Tag Immutability and Why You Need It
Harbor, the technology behind Container Registry, cannot (yet) deal with the situation when *more than one image has the same tag*. When there is an image in the registry with a certain tag, and then another image with the same tag is pushed to it, the first image *loses* its tag. The second image, pushed later, retains the tag but only until the next image with the same tag is pushed. 

Thus, the very purpose of tags existence &ndash; helping to differentiate between images &ndash; becomes a bit meaningless since the images override each other. The reason behind this trouble is that, for now, Harbor cannot match tags and SHA256 hashes. Therefore, hashes remain the only reliable image reference.

To rehabiliate the tags, Harbor allows you to specify tag immutability rules, although they must be set manually for each tag that can be a subject to repetition. The immutability won't allow an image with the same tag to be pushed into the repository. To be more precise, the policy is about a pair of an artifact and its tag. 


> **Note:** <ol>
> <li>
> If you add a tag into an immutability policy, <strong>you won&rsquo;t be able</strong> to perform the following actions with this artifact from anywhere in the GUI or you command line tool:
> <ul>
> <li>delete the tagged artifact completely;</li>
> <li><a href="/docs/user-manual/images/tags.md#retagging-images">re-tag the artifact</a> that is assigned the tag involved in the immutability policy;</li>
> <li>alter the tagged artifact through a <a href="/docs/administration-manual/replication/index.md">replication from another target registry</a> or in any other way.</li>
> </ul>
> </li>
> <li>
> You still can perform any operations with other tags assigned to the same artifact, even though the tags are attached to the same SHA256 hash/digest.
> </li>
> </ol>


## Create a Tag Immutability Policy

* Inside a project, go to the **Policy** tab;
* Switch to **TAG IMMUTABILITY** (2);
* Click **ADD RULE** (3);

![](../add_tag_rule_2.png)

* To select repositories and tags, specify matching patterns as explained [here](/docs/user-manual/double-starred-patterns/index.md);

![](../add_immutability_rule.png)

## Manage Immutability Policies

You can edit, disable/enable, and delete a tag immutability rule using the **Action** button next to each rule.
![](../manage_immutability.png)
Disabled rules will be marked with a red exclamation mark.