awesome-copilot/skills/azure-container-registry-cli/references/build-and-tasks.md

Builds & ACR Tasks

Table of Contents

• Quick Build (az acr build)
• Run a Command or Multi-Step Task Once (az acr run)
• ACR Tasks (az acr task)
• Triggers
• Multi-Step Task YAML
• Agent Pools

---

Quick Build (az acr build)

Builds in Azure and pushes to the registry — no local Docker daemon required:

# Build from the current directory and push
az acr build --registry {registry} --image app:v1 .

# Custom Dockerfile, build args, target platform
az acr build --registry {registry} --image app:v1 \
  --file docker/Dockerfile.prod \
  --build-arg VERSION=1.2.3 \
  --platform linux/amd64 .

# Cross-platform: each build produces ONE single-architecture image for the target platform
az acr build --registry {registry} --image app:v1-arm64 --platform linux/arm64 .
# For a true multi-arch image, build once per platform under arch-specific tags, then
# assemble and push a manifest list (docker manifest create/push, or docker buildx locally)

# Build directly from a Git repo (no local clone)
az acr build --registry {registry} --image app:v1 https://github.com/{org}/{repo}.git#{branch}:{folder}

# Build without pushing (validation only)
az acr build --registry {registry} --image app:test --no-push .

Notes:

• The build context is uploaded; use a .dockerignore to keep it small.
• Tag with a unique value per build (git SHA, run ID) — avoid relying on latest.

Run a Command or Multi-Step Task Once (az acr run)

# Run a container command in the registry's task runner (context /dev/null = no upload)
az acr run --registry {registry} --cmd '{registry}.azurecr.io/app:v1' /dev/null

# Execute a multi-step task file against the current directory
az acr run --registry {registry} --file acb.yaml .

ACR Tasks (az acr task)

Persistent, triggerable build definitions:

# Create a task that builds on every commit to main
az acr task create --registry {registry} --name build-app \
  --image "app:{{.Run.ID}}" \
  --context https://github.com/{org}/{repo}.git#main \
  --file Dockerfile \
  --git-access-token {pat} \
  --commit-trigger-enabled true \
  --base-image-trigger-enabled true

# Manually trigger, list, inspect
az acr task run --registry {registry} --name build-app
az acr task list --registry {registry} --output table
az acr task list-runs --registry {registry} --name build-app --output table
az acr task logs --registry {registry} --name build-app        # latest run
az acr task logs --registry {registry} --run-id {run-id}

# Update / disable / delete
az acr task update --registry {registry} --name build-app --image "app:{{.Run.ID}}"
az acr task update --registry {registry} --name build-app --status Disabled
az acr task delete --registry {registry} --name build-app --yes

Useful run variables for --image: {{.Run.ID}}, {{.Run.Commit}}, {{.Run.Branch}}, {{.Run.Date}}.

⚠️ On ABAC-enabled registries (roleAssignmentMode = AbacRepositoryPermissions), tasks and quick builds/runs have no default access to the source registry. Pass --source-acr-auth-id [caller] to az acr build/az acr run, and --source-acr-auth-id [system] (or a user-assigned identity resource ID) to az acr task create/update, then grant that identity the Container Registry Repository ... roles. Ensure the task actually has that identity — add --assign-identity [system] at creation, or run az acr task identity assign on an existing task, before referencing it.

Triggers

# Timer trigger (cron in UTC) — e.g., nightly rebuild
az acr task timer add --registry {registry} --name build-app \
  --timer-name nightly --schedule "0 2 * * *"
az acr task timer list --registry {registry} --name build-app
az acr task timer remove --registry {registry} --name build-app --timer-name nightly

• Commit trigger: rebuild on push to the tracked branch (--commit-trigger-enabled).
• Base image trigger: rebuild automatically when the base image (e.g., a patched mcr.microsoft.com image) is updated (--base-image-trigger-enabled) — key for OS/framework patching.
• Timer trigger: cron schedules; also the standard way to schedule acr purge cleanup (see images-and-artifacts.md).

Tasks that access other registries or Azure resources can use an identity:

az acr task identity assign --registry {registry} --name build-app   # system-assigned
az acr task credential add --registry {registry} --name build-app \
  --login-server {other-registry}.azurecr.io --use-identity [system]

Multi-Step Task YAML

acb.yaml — build, test, then push only on success:

version: v1.1.0
steps:
  - build: -t $Registry/app:{{.Run.ID}} -f Dockerfile .
  - cmd: $Registry/app:{{.Run.ID}} run-tests
  - push:
      - $Registry/app:{{.Run.ID}}

# Run once
az acr run --registry {registry} --file acb.yaml .

# Or create a triggered task from the YAML
az acr task create --registry {registry} --name build-test-push \
  --file acb.yaml \
  --context https://github.com/{org}/{repo}.git#main \
  --git-access-token {pat}

Agent Pools

Premium SKU. Dedicated task compute — for more CPU, or one of the two supported ways to run tasks against a network-restricted registry (the other being trusted services + the task network bypass policy, see networking-and-geo.md):

az acr agentpool create --registry {registry} --name pool1 --tier S2   # S1/S2/S3/I6

# For the firewall/VNet scenario, the pool MUST be attached to a subnet that can
# reach the registry's private endpoint — without --subnet-id it runs outside the VNet
az acr agentpool create --registry {registry} --name pool1 --tier S2 \
  --subnet-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/virtualNetworks/{vnet}/subnets/{subnet}

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

# Target the pool
az acr build --registry {registry} --agent-pool pool1 --image app:v1 .
az acr task create --registry {registry} --name build-app --agent-pool pool1 ...