az acr build: Cloud Image Builds & CI Errors

Build a container image in the cloud with ACR Tasks and push it - no local Docker.

az acr build queues a build of your Dockerfile on Azure Container Registry Tasks and pushes the result to the registry. Like Cloud Build, it removes the need for a Docker daemon on the CI agent.

What it does

az acr build --registry <name> --image <repo:tag> <context> uploads the build context, builds the Dockerfile remotely on ACR Tasks, and pushes the tagged image into the registry on success. It streams build logs back to your terminal and returns nonzero on failure.

Common usage

# Build from the current directory and push
az acr build \
  --registry myregistry \
  --image my-app:latest .

# Specify a Dockerfile and build args
az acr build --registry myregistry --image my-app:v2 \
  --file Dockerfile.prod \
  --build-arg ENV=prod .

Common error in CI: build context too large / Dockerfile not found

Builds fail with "Dockerfile not found" when --file or the context path is wrong, or are slow/rejected because the uploaded context is huge (no .dockerignore). Fix: run from the directory containing the Dockerfile (or point --file at it), and add a .dockerignore to keep node_modules/.git out of the uploaded context. A "quota exceeded" or "registry not found" error means the wrong --registry name or an SKU/quota limit - confirm the registry exists and the SKU supports Tasks. The identity needs Contributor/AcrPush on the registry.

Key options

Related guides