Skip to article
Containers Azure Container Registry

ACR repository

An ACR repository is the named place inside Azure Container Registry where related container images or OCI artifacts live. A repository is not the whole registry; it is one lane inside it, such as payments-api or base/python. Each.

Source: Microsoft Learn - About registries, repositories, and artifacts Reviewed 2026-06-01

Exam trap
Deploying production with latest tags and losing evidence when the tag later points to a different digest.
Production check
Can you map each production workload to a repository, tag, digest, and owning pipeline?
Practice this topic Microsoft Learn
Article details and learning context
Aliases
Azure Container Registry repository, container registry repository, image repository
Difficulty
fundamentals
CLI mappings
5
Last verified
2026-06-01
Review level
field-manual-complete
Article depth
field-manual-complete
Learning paths Graph Container platform readiness ACR repository
Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

An ACR repository is the named place inside Azure Container Registry where related container images or OCI artifacts live. A repository is not the whole registry; it is one lane inside it, such as payments-api or base/python. Each pushed image version appears through tags and manifests. Teams use repositories to organize images by application, base image, platform component, or promotion stage. In plain language, it is where a deployment platform looks when it needs the image for a specific service.

Why it matters

ACR repositories matter because container deployments are only as reliable as the artifact location they reference. A wrong repository name, mutable latest tag, deleted manifest, missing pull permission, or broad token can break rollouts across clusters and environments. Repositories also become ownership boundaries: teams can decide who publishes images, who can delete them, how long old tags stay, and which digest was approved for production. Without repository discipline, registries turn into junk drawers full of stale images, unclear provenance, and risky permissions. Good repository design supports secure release promotion and faster incident recovery. That discipline also improves vulnerability response when a base image must be traced quickly.

Official wording and source

Microsoft Learn explains that Azure Container Registry stores container images and other artifacts in repositories. An ACR repository is a named collection of images or artifacts inside a registry, usually containing versions identified by tags and immutable manifests identified by digests.

Open Microsoft Learn

Technical context

Technically, an ACR repository belongs to an Azure Container Registry and stores manifests, layers, tags, metadata, and supported OCI artifacts. AKS, Azure Container Apps, App Service custom containers, pipelines, scanners, and ACR Tasks reference repositories when pulling, pushing, scanning, building, or deleting images. Repository operations live in the registry data plane, while registry configuration, networking, identity, and SKU live around it. Important details include tag mutability, digest references, retention, repository permissions, content trust assumptions, private endpoints, and pull identity configuration.

Exam context

Compare with

ACR manifest ACR token Container image Azure Container Registry

Where it is used

Where you see it

  1. In the Azure Container Registry Repositories blade, each repository appears with tags, manifests, digests, timestamps, and delete options used during release review. and incident response
  2. In Kubernetes manifests, Container Apps revisions, and pipeline variables, repository names appear inside image references that runtimes pull during deployment. across development, staging, and production
  3. In CLI and security reviews, repository output reveals stale tags, protected digests, broad permissions, missing pull access, and artifacts safe for cleanup. during cleanup reviews

Common situations

  • Organize container images by application or platform component so runtime image references remain predictable and owned.
  • Trace a production workload back to the exact repository, tag, and digest used during a release or incident.
  • Lock down repository-level push, pull, and delete behavior when many teams share one registry.
  • Clean stale tags and manifests without removing approved rollback images or compliance evidence.
  • Standardize base-image repositories so application teams rebuild from approved and patched foundations.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Cleaning registry sprawl before AKS platform consolidation A software vendor ran eight AKS clusters and one shared registry. Years of experiments left hundreds of poorly named repositories, and platform engineers could not tell which images were still used.
Scenario

A software vendor ran eight AKS clusters and one shared registry. Years of experiments left hundreds of poorly named repositories, and platform engineers could not tell which images were still used.

Goals
  • Map production workloads to active ACR repositories and digests.
  • Retire abandoned repositories without breaking rollback.
  • Standardize repository names before cluster consolidation.
  • Reduce time spent investigating image-pull failures.
Approach using ACR repository

The platform team exported repository, tag, and manifest metadata with Azure CLI and compared it against running Kubernetes image references from each cluster. Repositories without owners were quarantined by disabling writes before deletion. Active services were renamed into a standard pattern through pipeline changes, and production releases began recording digest values. Retention rules were adjusted to keep the last six approved releases per service. A dashboard showed repository owner, last push time, current digest, and cleanup status. Service owners approved each deletion candidate before the quarantine period ended.

Potential outcomes
  • Removed 38 percent of abandoned repositories without a production image-pull incident.
  • Image-pull investigations dropped from 45 minutes to 12 minutes on average.
  • All production services gained owner metadata and recorded digest evidence.
  • Cluster consolidation finished with no unknown image dependencies left in the registry.
What to learn

ACR repositories become operational boundaries when teams need to prove which images are active, owned, and safe to remove.

Scenario 02 Protecting robotics base images used by factory deployments A robotics manufacturer maintained shared base images for factory controllers. Application teams sometimes pushed emergency changes into the same repositories, causing unpredictable rebuilds across plants.
Scenario

A robotics manufacturer maintained shared base images for factory controllers. Application teams sometimes pushed emergency changes into the same repositories, causing unpredictable rebuilds across plants.

Goals
  • Separate base-image repositories from application repositories.
  • Restrict who can push or delete approved base images.
  • Trace factory deployments to approved base-image digests.
  • Reduce rebuild failures caused by inconsistent tags.
Approach using ACR repository

The DevSecOps group created dedicated ACR repositories for approved operating-system and runtime base images. Repository permissions limited push and delete rights to the platform pipeline, while application teams could only pull. ACR Tasks rebuilt application images when approved base images changed, and release records stored base-image digest values. CLI checks ran before factory deployment windows to confirm repository attributes, tag age, and manifest availability. Mutable convenience tags stayed in development, but production used immutable release tags and digest evidence. Plant release managers verified the new pull path during maintenance rehearsals. before production resumed

Potential outcomes
  • Unauthorized base-image changes dropped to zero after repository-scoped controls were applied.
  • Factory rebuild failures tied to missing base tags fell by 73 percent.
  • Deployment records could identify the base-image digest for every plant controller.
  • Emergency patch rollout time improved from three days to 14 hours.
What to learn

ACR repository design helps protect shared image foundations that many downstream workloads rely on.

Scenario 03 Creating clean image promotion for a media streaming platform A media streaming platform promoted images by retagging across environments. During a launch, a staging tag was accidentally pulled by production workers, causing feature flags to behave incorrectly.
Scenario

A media streaming platform promoted images by retagging across environments. During a launch, a staging tag was accidentally pulled by production workers, causing feature flags to behave incorrectly.

Goals
  • Make image promotion deterministic across environments.
  • Prevent production from pulling staging-only tags.
  • Keep rollback images discoverable for release engineers.
  • Shorten incident review when image versions are disputed.
Approach using ACR repository

Release engineers reorganized ACR repositories so each service had a consistent repository path and environment promotion was recorded through immutable release tags plus digests. Pipeline policies prevented staging tags from being used in production manifests. Azure CLI validation checked that the production tag and digest existed before deployment and wrote the manifest metadata to the release ticket. Old tags were retained according to release cadence, not simple age, so launch rollback images were preserved. Release managers practiced rollback using stored digest values before the next launch. for launch readiness safely

Potential outcomes
  • Wrong-environment image pulls were eliminated in the next three major launches.
  • Release approval time improved 28 percent because digest checks were automated.
  • Rollback image lookup dropped from 30 minutes to under five minutes.
  • Incident reviews stopped debating which image ran because the digest was recorded.
What to learn

ACR repositories support safer promotion when repository names, tags, and digests are treated as release evidence.

Azure CLI

I use Azure CLI for ACR repositories because repository questions usually happen under release pressure. I need to list repositories, inspect tags, compare manifests, find digests, and confirm delete or pull behavior quickly. The portal is useful for browsing, but CLI output can be pasted into incident notes, retention reviews, deployment records, and pipeline checks. It also works across many registries, which is where naming drift and stale images appear. After years of container operations, I do not trust a deployment until I can prove the image reference resolves to the expected repository and digest. before production promotion. every time

Useful for

  • List repositories in a registry and identify unexpected service names, abandoned repositories, or naming drift.
  • Show tags and manifest metadata to confirm which image version or digest a deployment should pull.
  • Disable writes or deletes on a repository before a release freeze or investigation.
  • Delete stale repositories only after confirming retention, rollback, and ownership evidence.

Before you run a command

  • Confirm registry name, subscription, tenant, repository name, and whether the command targets tags, manifests, or repositories.
  • Check permissions carefully because repository delete and manifest delete can remove rollback artifacts needed by production.
  • Use output formats that preserve digest values exactly, since digest evidence is stronger than tag names.
  • Verify whether repositories are managed by pipeline policy or retention automation before making manual changes.

What the output tells you

  • Repository list output shows which named artifact collections exist and often reveals abandoned or incorrectly named services.
  • Tag output shows visible image versions, timestamps, and whether release naming matches the expected promotion process.
  • Manifest metadata shows digest, media type, tags, created time, and attributes useful for rollback and audit decisions.
  • Permission or not-found errors point to wrong registry names, missing identities, private network restrictions, or deleted artifacts.

Mapped commands

ACR repository commands

direct 
az acr repository list --name <registry-name> --output table
az acr repositorydiscoverContainers
read-only Microsoft Learn 
az acr repository show-tags --name <registry-name> --repository <repository> --output table
az acr repositorydiscoverContainers
read-only Microsoft Learn 
az acr manifest list-metadata --registry <registry-name> --name <repository>
az acr manifestdiscoverContainers
read-only Microsoft Learn 
az acr repository update --name <registry-name> --repository <repository> --write-enabled false
az acr repositoryconfigureContainers
mutating Microsoft Learn 
az acr repository delete --name <registry-name> --repository <repository>
az acr repositoryremoveContainers
destructive Microsoft Learn

Architecture context

In cloud-native architecture, an ACR repository sits between the build system and the runtime platform. Source code becomes an image, the image is pushed to a repository, and workloads pull a tag or digest during deployment. Architects should design repository naming around service ownership, environment promotion, base-image governance, and artifact lifecycle. Private registry networking, managed identities, scope maps, retention policy, vulnerability scanning integrations, and CI/CD pipelines all intersect at the repository. Experienced Azure architects prefer immutable release evidence, usually digest-based, rather than letting production depend on ambiguous tags that can move silently. This discipline keeps artifact flow understandable as teams and clusters multiply.

Security
Security for an ACR repository focuses on who can push, pull, delete, retag, or list artifacts, and how runtimes authenticate. Broad registry-wide permissions are convenient but dangerous when multiple teams share one registry. Use Microsoft Entra authentication, managed identities for AKS or Container Apps pulls, repository-scoped tokens when appropriate, private endpoints, and clear separation between publisher and runtime identities. Avoid relying on mutable tags as approval evidence. Deletion rights deserve special review because removing a manifest can break rollback. Repositories may also need scanning, provenance, and base-image controls for supply-chain risk. Security reviews should include evidence from tags, digests, and recent delete activity.
Cost
Repository cost is mostly indirect but real. Images consume registry storage, duplicated layers can accumulate, stale tags hide abandoned builds, and Premium registries add cost for features such as private endpoints, higher limits, and geo-replication. Pull patterns can also affect data transfer and runtime performance in distributed environments. Cost control should not delete blindly, because rollback images and audit evidence have value. Instead, teams should apply retention rules, remove unreferenced artifacts, standardize base images to share layers, and tag repositories with owners. Repository hygiene is a FinOps practice as much as a cleanup task. Monthly reviews should separate necessary rollback history from forgotten build noise.
Reliability
Reliability for an ACR repository means the required image can be pulled during deployment, scale-out, node replacement, and rollback. Failures often come from deleted tags, missing permissions, private DNS problems, registry throttling, or depending on a tag that no longer points to the tested digest. Geo-replication and Premium SKU features can reduce regional pull latency and availability risk for distributed workloads. Operators should preserve rollback images, document retention rules, and test pull access from each runtime environment. A reliable repository makes artifact availability predictable during both normal releases and emergencies. Deployment runbooks should verify repository access before draining nodes or starting major rollouts.
Performance
Performance for an ACR repository appears during build, push, pull, deployment, and scale-out. Large images, many layers, distant registries, private endpoint DNS issues, and cold node caches can slow rollouts. Pulling by digest does not make images smaller, but it makes artifact selection deterministic. Premium registry capabilities, geo-replication, smaller base images, layer reuse, and runtime-side caching can improve practical deployment speed. Operators should measure image size, pull failures, pull duration, and rollout timing. Repository organization also affects operational performance because clean names and tags reduce search time during incidents. During incidents, fast repository discovery can matter as much as raw network throughput.
Operations
Operations teams inspect ACR repositories to answer practical release questions: which tags exist, which digest is deployed, who pushed recently, which images are stale, and what can be safely removed. CLI is heavily used because repository and manifest operations are frequent during incident response and cleanup. Runbooks should cover tag listing, manifest metadata, delete protection decisions, pull-permission validation, retention review, and pipeline naming conventions. Good operations connect repository data to deployment records so teams can trace a running pod or container app back to the exact artifact it pulled. Operators should also compare repository state against runtime references before deleting anything.

Common mistakes

  • Deploying production with latest tags and losing evidence when the tag later points to a different digest.
  • Granting broad registry push and delete permissions to every pipeline instead of limiting repository actions.
  • Deleting old-looking tags without confirming whether a cluster still uses that digest for rollback.
  • Using inconsistent repository names across environments so promotion scripts quietly pull the wrong image.