Image tag mutability

You can configure a repository to turn on tag immutability to prevent image tags from being overwritten. After the repository is configured for immutable tags, an ImageTagAlreadyExistsException error is returned if you attempt to push an image with a tag that is already in the repository. When tag immutability is turned on for a repository, this affects all tags and you cannot make some tags immutable while others aren't.

You can use the AWS Management Console and AWS CLI tools to set image tag mutability for either a new repository during creation or for an existing repository at any time. For console steps, see Creating a private repository and Editing a private repository.

To create a repository with immutable tags configured

Use one of the following commands to create a new image repository with immutable tags configured.

• create-repository (AWS CLI)

  aws ecr create-repository --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2

• New-ECRRepository (AWS Tools for Windows PowerShell)

  New-ECRRepository -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force

To update the image tag mutability settings for an existing repository

Use one of the following commands to update the image tag mutability settings for an existing repository.

• put-image-tag-mutability (AWS CLI)

  aws ecr put-image-tag-mutability --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2

• Write-ECRImageTagMutability (AWS Tools for Windows PowerShell)

  Write-ECRImageTagMutability -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force