Set the repository's image tag mutability to Immutable, in the console or with the AWS CLI. After that, pushing an image to a tag that already exists fails with ImageTagAlreadyExistsException. The setting applies to all tags in the repository, with an optional exclusion list for a few tags you still need to move.
Why bother
A tag is a pointer. Without immutability, anyone with push rights can point v1.8.0 at different content, and every deploy that references the tag silently changes. Immutable tags make a release tag mean one image. Pinning by digest is stronger and still worth doing, but immutable tags are a cheap guardrail at the registry. See why you should sign the digest, not the tag.
Steps in the console
- Open the Amazon ECR console and choose the Region that holds the repository.
- Under Private registry, choose Repositories and select the repository.
- Choose Actions, then Repository under Edit.
- For Image tag immutability, choose Immutable.
- Optionally add tag names or wildcards to the Immutable tag exclusion box for tags that may still be updated.
- Save.
Steps with the CLI
For a new repository, AWS documents this form:
aws ecr create-repository \
--repository-name my-service \
--image-tag-mutability IMMUTABLE \
--region us-east-2
To allow exceptions, use the IMMUTABLE_WITH_EXCLUSION value together with exclusion filters of type WILDCARD. For an existing repository, the put-image-tag-mutability command changes the setting.
What it does and does not do
| Question | Answer |
|---|---|
| Can an existing tag be repointed? | No, the push is rejected |
| Can you apply it to only some tags? | Only through the exclusion filters, not tag by tag in the basic setting |
| Does it stop deletion? | It is about overwriting, so control delete rights separately |
| Does it prove who built the image? | No. Add signing and provenance |
One catch from AWS's own page: Mutable is the recommended choice for repositories that use pull through cache, so ECR can refresh cached images. Do not flip a cache repository to Immutable without testing.
Change your pipeline to match
Once tags are immutable, a rebuild must use a new tag. A common scheme is the semantic version plus the commit SHA, with deployments referencing the digest. Do not rely on a moving latest tag in production. If a CI job fails with the exception, that is the control working: bump the version rather than disabling the setting.
Safeguard's container image scanning and policy gates can check the digest you are about to deploy, whatever tag it carries. Try it with the free scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how findings attach to an image rather than to a tag name.
Quick check
Can I make only one tag immutable?
The base setting affects all tags. AWS offers exclusion filters so a few tags stay mutable while the rest are immutable, or the reverse.
What error will my CI see?
ImageTagAlreadyExistsException when you push to a tag that already exists in an immutable repository.
Sources
Last reviewed: 19 October 2026.
