Configure repository immutability to prevent image tag overwrites - Container Registry

When you deploy container images to production, you need to ensure that a tagged image cannot be silently replaced by a later push. Image tag immutability prevents any existing tag from being overwritten: if a push targets an existing tag, ACR rejects it with the error The requested tag already exists and cannot be overwritten.

Image tag immutability is configured per repository. The latest tag is exempt and can still be overwritten even when immutability is enabled.

Prerequisites

Before you begin, ensure that you have:

An ACR Enterprise Edition instance
A repository in that instance

Enable image tag immutability

Log on to the Container Registry console.
In the top navigation bar, select a region.
In the left-side navigation pane, click Instances.
On the Instances page, click the Enterprise Edition instance you want to manage.
In the left-side navigation pane, choose Repository > Repositories.
On the Repositories page, find the repository you want to configure and click Manage in the Actions column.
On the repository details page, click Edit in the Details section.
In the Modify Settings dialog box, select Immutable and click Confirm.

Note
To disable image tag immutability, clear Immutable.

Verify image tag immutability

Push an image with a non-latest tag to the repository.

docker push example-registry-vpc.cn-hangzhou.cr.aliyuncs.com/test/example:v1

Push another image using the same tag.
The push is rejected with the following error:
```
The requested tag already exists and cannot be overwritten.
```

Push an image with the latest tag.

docker push example-registry-vpc.cn-hangzhou.cr.aliyuncs.com/test/example:latest

Push another image using the latest tag.

The push succeeds and the previous latest image is overwritten. This confirms that the latest tag is exempt from immutability.
Clear the Immutable checkbox to disable image tag immutability.
Push another image using the same non-latest tag as in step 1.

The push succeeds and the image overwrites the previous one. This confirms that clearing Immutable restores normal push behavior.