# Make tags immutable

Refuse a push that would move an existing tag to a different image, with exceptions such as latest.

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

**Console**
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.

**CLI**
```sh
dcloud ecr repositories update repository-id --tag-mutability immutable \
  --tag-mutability-exclusions latest
```

**API**
```http
PATCH /ecr/api/repositories/repository-id
{ "tagMutability": "immutable", "tagMutabilityExclusions": ["latest"] }
```

**Terraform**
```hcl
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

- [Delete a tag or an image](delete-a-tag-or-image.md)
- [Push an image](push-an-image.md)
- `ecr.repositories.update` · `dcloud ecr repositories update` · `dcloud_ecr_repository`
