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:UpdateRepository on the repository.
  • In the console, also ecr:DescribeRepositories on it; without it the repository's page answers 404.

Turn it on

  1. Open Image repositories, then open the repository.
  2. Open the Settings tab.
  3. Under Image tags, choose Make tags immutable. It is saved at once.
  4. (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.

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.
Did this page help you?