Add Tag Exclusions to ACR Purge

Start with the acr purge command and its existing --filter, --ago, --keep, --max-tags, and --untagged paths, using prior work in Azure/acr-cli#59, #60, #256, and #428 for context. Add repeatable --exclude-tags and --exclude-filter handling, then cover the listed retention, dry-run, pagination, untagged, and ACR Task cases; update command help and the README with task examples.

Add Tag Exclusions to ACR Purge

What is the problem you're trying to solve?

acr purge --filter lets users select tags for deletion, but there is no straightforward way to protect a known set of tags.

Common examples include:

• Tags currently deployed to a Kubernetes cluster
• latest or stable
• Release tags
• A generated list of tags that are still in use

Negative lookaheads can cover some of these cases, but they become difficult to build and maintain, especially for a long list of exact tags.

This also needs to work with the normal ACR Task flow:

az acr run \
    --registry example \
    --cmd '{{ .Run.Registry }}/acr:latest purge ...' \
    /dev/null

Because purge tasks commonly use /dev/null as their context, requiring an exclusion file would not be practical.

Describe the solution you'd like

Add two optional, repeatable flags:

--exclude-tags <repository-regex>:<tag>[,<tag>...]
--exclude-filter <repository-regex>:<tag-regex>

--exclude-tags would be used for exact tag names:

# Keep several tags in the app repository
--exclude-tags "^app$:v1.2.3,v1.2.4,v1.2.5"

# Keep v1.0 in all repositories beginning with app
--exclude-tags "^app.*$:v1.0"

# Keep latest in every repository
--exclude-tags ".*:latest"

--exclude-filter would be used when the tags themselves follow a pattern:

# Keep release tags in all repositories beginning with app
--exclude-filter "^app.*$:^release-.*$"

The flags could be combined:

az acr run \
    --registry example \
    --cmd '{{ .Run.Registry }}/acr:latest purge -r {{ .Run.Registry }} --filter ".*:.*" --exclude-tags ".*:latest,stable" --exclude-tags "^app.*$:v1.0,v1.1" --exclude-filter "^worker.*$:^production-.*$" --ago 7d' \
    /dev/null

The repository portion would use the same regex behavior as --filter. Tags passed to --exclude-tags would be treated as literal values.

Any matching exclusion would take precedence over --filter. In other words, a tag would only be considered for deletion when it matches --filter and does not match any exclusion.

Exclusions should be applied before --ago, --keep, or --max-tags. This is important so protected tags do not consume positions in count-based retention.

Expected behavior

• Both flags are optional and repeatable.
• Values from every occurrence are combined.
• --exclude-tags accepts comma-separated literal tags for one repository expression.
• Whitespace around comma-separated tags is ignored.
• --exclude-filter accepts a repository regex and a tag regex.
• Duplicate exact tags are harmless.
• Invalid expressions and malformed tag lists fail before deletion begins.
• Dry-run and actual purge use the same exclusion logic.
• Exclusions apply to both the age/--keep and --max-tags paths.
• Existing behavior is unchanged when no exclusions are supplied.
• The existing numeric --keep flag is unchanged.
• When --untagged is used, manifests referenced by excluded tags are not considered dangling.
• The exclusion flags are invalid with --untagged-only, since that mode does not evaluate tags.

Acceptance criteria

• Exact tags can be excluded from one repository, a matching set of repositories, or all repositories.
• Multiple exact tags can be supplied without repeating the repository for each tag.
• Exact exclusions and regex exclusions can be used together.
• Excluded tags are never selected for deletion and do not count toward --keep or --max-tags.
• The behavior works through az acr run without requiring a task source context.
• Tests cover multiple flags, repository patterns, pagination, dry-run, --ago, --keep, --max-tags, and --untagged.
• Command help and the README include ACR Task examples.

Prior work

This has been requested and worked on a few times:

• Azure/acr-cli#59 was opened by @dominicdejacomo in 2019 for protecting tags used by Kubernetes workloads.
• Azure/acr-cli#60 was implemented by @angrox in 2019. Review requested precompiled expressions and additional tests, but the PR was not completed.
• Azure/acr-cli#256 was opened by @jan-dolejsi in 2024 for maintaining an explicit list of tags that should survive purge.
• Azure/acr-cli#428 was opened by @sashokbg in 2025 based on the earlier work. It added exclusion precedence, documentation, and tests, but was not updated after review.

Any implementation should build on and credit that prior work while fitting into the current purge retention paths.

Potential follow-up

ACR Tasks can run with a source context, so a future --exclude-tags-file option may be useful for very large or generated exclusion lists. The file could contain one repository and tag entry per line and be included in the task context.

File input is outside the initial scope of this proposal. Command-line exclusions work with the common /dev/null task flow and avoid defining a file format, path behavior, and task-context requirements as part of the first implementation.