Make tags immutable
Refuse a push that would move an existing tag to a different image, with exceptions such as latest.
Last updated 18 November 2026View as Markdown
With immutable tags, a release tag once pushed always means the same image. Replace repository-id with the repository's id.
Prerequisites
- Permission for
ecr:UpdateRepositoryon the repository. - In the console, also
ecr:DescribeRepositorieson it; without it the repository's page answers 404.
Turn it on
- Open Image repositories, then open the repository.
- Open the Settings tab.
- Under Image tags, choose Make tags immutable. It is saved at once.
- (Optional) For Tags that stay mutable, enter patterns separated by commas, such as
latest, main-*, then choose Save.
Allow tags to move turns it off again.
dcloud ecr repositories update repository-id --tag-mutability immutable \
--tag-mutability-exclusions latestPATCH /ecr/api/repositories/repository-id
{ "tagMutability": "immutable", "tagMutabilityExclusions": ["latest"] }resource "dcloud_ecr_repository" "my_app" {
name = "my-app"
tag_mutability = "immutable"
tag_mutability_exclusions = ["latest"]
}Result
A push that would move an existing tag to a different image is refused with TAG_INVALID, and
docker push prints tag "v1.2.0" is immutable in this repository and already points at a different image; push a new tag, or delete this one first.
- Pushing the same image under the tag again succeeds, so a retried CI job does not fail.
- Tags matching an exclusion (up to 10 patterns;
*matches anything) still move. - Deleting a tag is still allowed, with
ecr:DeleteImage; after that the tag can be pushed anew.
Related
Did this page help you?