Preventing image tags from being overwritten in Amazon ECR

You can prevent image tags from being overwritten by turning on tag immutability in a repository. After tag immutability is turned on, the ImageTagAlreadyExistsException error is returned if you push an image with a tag that is already in the repository. Tag immutability affects all tags. 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 a new repository or for an existing repository. To create a repository using console steps, see Creating an Amazon ECR private repository to store images.

Setting image tag mutability (AWS Management Console)

To set image tag mutability

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories.

2. From the navigation bar, choose the Region that contains the repository to edit.

3. In the navigation pane, choose Repositories.

4. On the Repositories page, choose the Private tab and then select the repository to edit and choose Edit.

5. For Tag immutability, choose the tag mutability setting for the repository. Repositories configured with immutable tags prevent image tags from being overwritten. For more information, see Preventing image tags from being overwritten in Amazon ECR.

6. For Image scan settings, while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan configuration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic scanning as well as define filters to specify which repositories are scanned. For more information, see Scan images for software vulnerabilities in Amazon ECR.

7. For Encryption settings, this is a view only field as the encryption settings for a repository can't be changed once the repository is created.

8. Choose Save to update the repository settings.

Setting image tag mutability (AWS CLI)

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 a 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