---
title: "Deploy to Azure Container Registry"
description: "This document provides examples of deploying to Azure Container Registry."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-06"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Deploy to Azure Container Registry

In this how-to guide, you will learn how to configure CircleCI to deploy to Azure Container Registry.

## Introduction

This page describes a simple deployment to the Azure Container Registry (ACR) using the CircleCI ACR orb and `version 2.1` configuration.

To take advantage of [Secrets Masking](https://circleci.com/docs/guides/security/contexts/#secrets-masking), it is best practice to set environment variables at the [Project Level](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-project) or within a [Context](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-context).

In addition to the orb described below, CircleCI has created an Azure convenience image focusing on [deployment: `cimg/azure`](https://circleci.com/developer/images/image/cimg/azure).

For detailed information about the Azure ACR orb, including all options, refer to the [CircleCI ACR Orb Reference](https://circleci.com/developer/orbs/orb/circleci/azure-acr) page.

## 1\. Provide environment variables to CircleCI

Whether you require a user or service principal login, you will need to provide environment variables for username, password and tenant to CircleCI. For user logins use environment variable names as follows:

*   `AZURE_USERNAME`
    
*   `AZURE_PASSWORD`
    
*   `AZURE_TENANT`
    

For service principal logins use:

*   `AZURE_SP`
    
*   `AZURE_SP_PASSWORD`
    
*   `AZURE_SP_TENANT`
    

## 2\. Deploy to ACR

Use the orb’s `build-and-push-image` job to build your image and deploy it to ACR. Note the use of workflows to deploy only if the current branch is `main`.

Make sure to replace any placeholder versions in the example.

```yaml
version: 2.1 # Use version 2.1 config to get access to orbs, pipelines

orbs:
  azure-acr: circleci/azure-acr@0.2.2 # Use the Azure ACR orb in your config

workflows:
  build-deploy:
    jobs:
      - azure-acr/build-and-push-image:
          dockerfile: <name-of-your-dockerfile> # defaults to `Dockerfile`
          path: <path-to-your-dockerfile> # Defaults to working directory
          login-server-name: <your-login-server-name> # e.g. {yourregistryname}.azure.io
          registry-name: <your-ACR-registry-name>
          repo: <URI-to-your-login-server-name>
          filters: pipeline.git.branch == "main" # only run the build-and-push-image job on the main branch
```

If pushing to your repository is required, see the [Users, Organizations, and Integrations Guide](https://circleci.com/docs/guides/server/permissions-authentication/users-organizations-and-integrations-guide/#enable-project-to-check-out-additional-private-repositories). Then, configure the Azure Web App to use your production branch.