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 – helping to differentiate between images – 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.


  1. If you add a tag into an immutability policy, you won’t be able to perform the following actions with this artifact from anywhere in the GUI or you command line tool:

  2. 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.

Create a Tag Immutability Policy

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

  • To select repositories and tags, specify matching patterns as explained here;

Manage Immutability Policies

You can edit, disable/enable, and delete a tag immutability rule using the Action button next to each rule. Disabled rules will be marked with a red exclamation mark.