Azure Container Registry CLI

GitHubOfficialFirst committed by AClerboisDistributed by GitHub

Skill
Tool integration
Cloud and DevOps
MIT
Low risk

From the author

Manage Azure Container Registry via the az acr CLI including registries, images, cloud builds, ACR Tasks, authentication, tokens, geo-replication, and networking. Use when working with ACR, az acr commands, pushing/importing/purging container images in Azure, or when the user mentions Azure Container Registry.

— the description by AClerbois

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The azure-container-registry-cli skill provides a comprehensive interface for interacting with Azure Container Registry (ACR) via the Azure CLI. It covers the full lifecycle of container registries, including creation, authentication, image management, cloud-based builds, and automated tasks. The skill emphasizes server-side operations like importing images and cloud builds to reduce local dependencies and improve efficiency in CI/CD pipelines.

What it does

Create and manage Azure Container Registry instances and configurations.
Authenticate local environments or services against registries.
Execute cloud-based container image builds without requiring a local daemon.
Automate image workflows using ACR Tasks with git, base-image, or timer triggers.
Perform server-side image operations such as importing and purging.
Manage registry security through RBAC roles, repository-scoped tokens, and network rules.

When to use it

When you need to build, push, or import container images directly within Azure.
When setting up automated image rebuilds or multi-step tasks.
When configuring registry access for CI/CD systems or Azure compute services.
When managing registry lifecycle, geo-replication, or network security settings.
When diagnosing connectivity or quota issues with a registry.

Advantages

Reduces local resource usage by offloading builds and image transfers to the cloud.
Integrates natively with Azure identity and access management systems.
Supports complex automation workflows through ACR Tasks.
Provides server-side tools for efficient image maintenance and cleanup.

Usage examples

“How do I build an image in the cloud using my current directory?”: The agent will provide the az acr build command, specifying the registry and image name to trigger a cloud-based build.
“How can I grant a service principal pull access to my registry?”: The agent will explain how to use az role assignment create with the AcrPull role scoped to the registry ID.
“Show me how to list all tags for a specific repository.”: The agent will provide the az acr repository show-tags command to display tags for the requested repository.
“How do I set up a nightly rebuild task for my application?”: The agent will guide you through creating an ACR task and adding a timer trigger using az acr task timer add.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/github/azure-container-registry-cli/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip azure-container-registry-cli.zip -d .agents/skills

Documentation by AClerbois

Azure Container Registry CLI

Manage Azure Container Registry (ACR) resources using the az acr command group of the Azure CLI.

CLI: az acr ships with core Azure CLI — no extension required (the acrtransfer extension is only needed for export/import pipelines).

Prerequisites

# Install Azure CLI
brew install azure-cli  # macOS
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash  # Linux
winget install Microsoft.AzureCLI  # Windows

# Sign in and select subscription
az login
az account set --subscription {subscription-id}

Quick Start

# Create a registry (SKU: Basic | Standard | Premium)
az acr create --resource-group {rg} --name {registry} --sku Standard

# Authenticate Docker/Podman against the registry
az acr login --name {registry}

# Build and push in the cloud — no local Docker needed
az acr build --registry {registry} --image app:v1 .

# Copy an image from another registry without pull/push
az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest

# List repositories and tags
az acr repository list --name {registry} --output table
az acr repository show-tags --name {registry} --repository app --orderby time_desc

# Diagnose registry connectivity and configuration
az acr check-health --name {registry} --yes

Key Principles

Prefer az acr build / ACR Tasks over local docker build + docker push: builds run in Azure, work without a local daemon, and integrate with triggers.
Prefer az acr import to move images between registries: it is server-side, faster, and requires no local storage.
Never enable the admin user for production — use Microsoft Entra identities (RBAC roles AcrPull/AcrPush, or Container Registry Repository Reader/Writer on ABAC-enabled registries), repository-scoped tokens, or managed identities.
Premium-only features: geo-replication, private endpoints, retention policies, connected registries, agent pools. (Repository-scoped tokens work in all tiers; zone redundancy is automatic in all tiers in supported regions.)

CLI Structure

az acr
├── create / delete / list / show / update   # Registry lifecycle
├── login                  # Docker credential helper (or --expose-token)
├── check-health / check-name / show-usage   # Diagnostics & quota
├── build                  # Cloud image build (quick task)
├── run                    # Run a command / multi-step task once
├── task                   # ACR Tasks (triggers, timers, logs, runs)
├── agentpool              # Dedicated task agent pools (Premium)
├── import                 # Server-side image copy into the registry
├── repository             # List/show/delete/untag repos & tags, lock images
├── manifest               # Manifest metadata, delete, OCI referrers
├── credential             # Admin user credentials (avoid in production)
├── token / scope-map      # Repository-scoped tokens (Premium)
├── replication            # Geo-replication (Premium)
├── network-rule           # IP network rules
├── private-endpoint-connection  # Private Link approvals
├── config                 # content-trust, retention, soft-delete, ...
├── cache / credential-set # Artifact cache (pull-through cache) rules
├── webhook                # Push/delete event webhooks
├── connected-registry     # On-premises / IoT connected registries
└── export-pipeline / import-pipeline / pipeline-run  # acrtransfer extension

Reference Files

Read the relevant reference file based on the user's task. Each file contains complete command syntax and examples for its domain.

File	When to read	Covers
`references/auth-and-security.md`	Login failures, permissions, CI/CD or AKS pull access	`az acr login` (incl. `--expose-token`), Entra RBAC roles, service principals, managed identities, `--attach-acr` for AKS, repository-scoped tokens & scope maps, admin user, content trust
`references/build-and-tasks.md`	Building images in Azure, automation, CI triggers	`az acr build`, `az acr run`, multi-step task YAML, `az acr task` (git/base-image/timer triggers, logs, runs), agent pools
`references/images-and-artifacts.md`	Managing repos, tags, cleanup, storage costs	`az acr import`, repository & manifest commands, untag vs delete, purge (`acr purge`), image locking, retention policy, soft delete, artifact cache, `show-usage`
`references/networking-and-geo.md`	Multi-region, private access, edge scenarios	Geo-replication, zone redundancy, private endpoints, network rules, dedicated data endpoints, connected registries, registry transfer pipelines

Files

ATTRIBUTION.mdAdded by AutoGineer891 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md5.0 KiB
references/auth-and-security.md7.5 KiB
references/build-and-tasks.md6.0 KiB
references/images-and-artifacts.md6.4 KiB
references/networking-and-geo.md6.8 KiB

references/images-and-artifacts.md

Images & Artifacts

Import Images (Server-Side Copy)
Repositories & Tags
Manifests
Untag vs Delete
Purge Old Images (acr purge)
Lock Images
Retention Policy & Soft Delete
Artifact Cache (Pull-Through Cache)
Storage Usage

Import Images (Server-Side Copy)

Preferred over docker pull + docker push — no local storage, keeps multi-arch manifests intact:

# From a public registry
az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest
az acr import --name {registry} --source docker.io/library/nginx:1.27 --image nginx:1.27

# From another ACR in the same tenant (by resource ID, no credentials needed)
az acr import --name {registry} \
  --source app:v1 \
  --registry /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/{src-registry}

# From a private registry with credentials
az acr import --name {registry} --source private.example.com/app:v1 \
  --username {user} --password {password}

# Overwrite an existing tag
az acr import --name {registry} --source docker.io/library/nginx:1.27 --image nginx:1.27 --force

Repositories & Tags

az acr repository list --name {registry} --output table

# Tags, newest first, with digest and timestamps
az acr repository show-tags --name {registry} --repository app \
  --orderby time_desc --detail --output table

az acr repository show --name {registry} --image app:v1        # tag attributes
az acr repository show --name {registry} --repository app      # repo attributes

Manifests

# Metadata for all manifests in a repo (digest, tags, size, timestamps)
az acr manifest list-metadata --registry {registry} --name app --output table

# One manifest's metadata / raw content
az acr manifest show-metadata --registry {registry} --name app:v1
az acr manifest show --registry {registry} --name app@sha256:{digest}

# Find untagged (orphaned) manifests
az acr manifest list-metadata --registry {registry} --name app \
  --query "[?tags==null].digest" --output tsv

Untag vs Delete

# Untag: removes only the tag; manifest + layers remain (still pullable by digest)
az acr repository untag --name {registry} --image app:v1

# Delete by tag: deletes the whole manifest and ALL other tags pointing to it
az acr repository delete --name {registry} --image app:v1 --yes

# Delete by digest (precise)
az acr repository delete --name {registry} --image app@sha256:{digest} --yes

# Delete an entire repository
az acr repository delete --name {registry} --repository app --yes

⚠️ Deleting by tag deletes the underlying manifest — other tags on the same image disappear too. Untag first if you only want to retire a tag name.

Purge Old Images (acr purge)

acr purge runs as an ACR Task (container mcr.microsoft.com/acr/acr-cli):

# Dry run first — ALWAYS
az acr run --registry {registry} \
  --cmd "acr purge --filter 'app:.*' --ago 30d --untagged --dry-run" /dev/null

# Delete tags older than 30 days matching the regex, plus untagged manifests
az acr run --registry {registry} \
  --cmd "acr purge --filter 'app:.*' --ago 30d --untagged" /dev/null

# Keep the 5 most recent tags regardless of age
az acr run --registry {registry} \
  --cmd "acr purge --filter 'app:.*' --ago 0d --keep 5 --untagged" /dev/null

# Schedule as a nightly task
az acr task create --registry {registry} --name purge-old-images \
  --cmd "acr purge --filter 'app:.*' --ago 30d --untagged" \
  --context /dev/null --schedule "0 3 * * *"

--filter takes repository:tag-regex and can be repeated for multiple repos.

⚠️ --untagged ignores --ago: it deletes every untagged manifest, including ones created moments ago (mid-push images, referrer artifacts). Omit --untagged if recent untagged manifests must survive — the age cutoff only applies to tagged images matched by --filter.

Lock Images

Prevent overwrite or deletion of critical tags (e.g., released versions):

# Read-only: cannot be overwritten or deleted
az acr repository update --name {registry} --image app:v1 --write-enabled false

# Undeletable but still overwritable
az acr repository update --name {registry} --image app:v1 --delete-enabled false

# Unlock
az acr repository update --name {registry} --image app:v1 --write-enabled true --delete-enabled true

Retention Policy & Soft Delete

Two distinct policies that cannot be enabled at the same time. Retention policy requires Premium; soft delete (preview) is available in all tiers but doesn't support geo-replicated or artifact-cache-enabled registries.

# Retention policy (Premium): auto-delete untagged manifests after N days (0 = immediately)
az acr config retention update --registry {registry} \
  --status enabled --days 7 --type UntaggedManifests
az acr config retention show --registry {registry}

# Soft delete (preview, all tiers): recover deleted artifacts within 1-90 days
az acr config soft-delete update --registry {registry} --status enabled --days 7
az acr repository list-deleted --name {registry}
az acr manifest restore --registry {registry} --name app:v1

Artifact Cache (Pull-Through Cache)

Cache upstream images (Docker Hub, MCR, GHCR, quay.io, ECR Public) in your registry — avoids rate limits and centralizes provenance:

# Optional: credentials for authenticated upstream (secrets live in Key Vault)
az acr credential-set create --registry {registry} --name dockerhub-creds \
  --login-server docker.io \
  --username-id https://{vault}.vault.azure.net/secrets/dh-user \
  --password-id https://{vault}.vault.azure.net/secrets/dh-pass

# Cache rule: docker.io/library/* -> {registry}.azurecr.io/dockerhub/*
az acr cache create --registry {registry} --name dockerhub-cache \
  --source-repo "docker.io/library/*" --target-repo "dockerhub/*" \
  --cred-set dockerhub-creds

az acr cache list --registry {registry} --output table

Then docker pull {registry}.azurecr.io/dockerhub/nginx:1.27 fetches through the cache.

Storage Usage

# Consumed storage vs SKU quota (Basic 10 GB / Standard 100 GB / Premium 500 GB included)
az acr show-usage --name {registry} --output table

Layers are deduplicated and shared across repositories; show-usage reports actual billable storage.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access, Needs a command-line tool

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by

AClerbois

Publisher

GitHub (Official)

Distributed by

GitHub

Source

github/awesome-copilot · skills/azure-container-registry-cli · commit 797337f

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Contributors

AClerbois

AutoGineer is not affiliated with or endorsed by AClerbois or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download azure-container-registry-cli.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by AClerbois

Azure Container Registry CLI

Prerequisites

Quick Start

Key Principles

CLI Structure

Reference Files

Files

references/images-and-artifacts.md

Images & Artifacts

Table of Contents

Import Images (Server-Side Copy)

Repositories & Tags

Manifests

Untag vs Delete

Purge Old Images (acr purge)

Lock Images

Retention Policy & Soft Delete

Artifact Cache (Pull-Through Cache)

Storage Usage

Requirements and compatibility

Security

Attribution and licence

Related skills

Modal

Cloud Infrastructure Network Engineer

Deployment Validation Cloud Architect

Airflow Dag Patterns

Cost Optimization

Hybrid Cloud Networking

Download ZIP