Build and run images with ACR Tasks

Run az acr build --registry myregistry --image helloacrtasks:v1 --file Dockerfile . and the console prints Packing source code into tar file to upload..., then Queued a build with build ID: da1, then Waiting for build agent..., and a minute later the image is in the registry. Nothing on your machine built it. Your Dockerfile expertise transfers directly, because ACR Tasks^[1] still runs docker build; only the command you type changes.

The ACR image management page owns an image once it exists in the registry: tagging strategy, digests, locks, import, and cleanup. This page owns how it got there and how it gets rebuilt: the four ways a build gets started, how a requirement's wording picks between them, and the one YAML file that lets a single run build, test, and publish.

The vocabulary this page uses

Azure Container Registry Tasks (ACR Tasks) is the set of features inside Azure Container Registry that builds container images on Azure compute for Linux, Windows, and Arm. Three words recur:

• A build context is the location of the source files a build reads, exactly as with a local docker build. It is the positional argument of az acr build: a local directory, a Git URL, a remote tarball, or an artifact already in a registry, each covered in the next section.
• A run is one execution. Every run gets a short run ID such as da1 that names its logs and is commonly reused as the image tag.
• A task is a saved Azure resource created with az acr task create that holds a context, a Dockerfile path, an image name, and its triggers. A quick task is the exception: it runs without leaving a task resource behind.

The shape of every run

The figure below traces those steps in order. Whichever of the three task scenarios started it (quick task, automatically triggered task, multi-step task, in that order below), a run always: takes a context; uploads or clones it; queues, at which point the run ID is assigned; waits for a build agent, which is Azure's compute, not yours; builds; and, in the quick-task case, pushes, leaving a run record: logs, status, and what it discovered. Near the end of the output, ACR Tasks reports the dependencies it discovered^[2] for the image, including the registry, repository, tag, and digest of the base image the FROM instruction resolved to. That dependency record is the entire basis of base-image tracking, which a later section builds on.

Reading what a run did

Every run produces log output. A manually triggered run streams it to your console and stores it; an automatically triggered run only stores it, so you read it afterwards with az acr task logs or in the portal. az acr task list-runs --registry myregistry --output table prints one row per run with a RUN ID, TASK, PLATFORM, STATUS, TRIGGER, STARTED, and DURATION column. TRIGGER is the column that tells you what started the run, and its four values (Manual, Commit, Image Update, Timer) organise the next four sections. The section after those covers the multi-step YAML file, which changes what a run does rather than what starts it: those two axes cover every mechanism on this page.

One consequence worth carrying forward: because the build happens in Azure rather than on the caller's machine, the caller needs Azure permissions rather than a container runtime. That is what makes ACR Tasks usable from Cloud Shell, from a pipeline agent, or from a workstation where installing Docker is not allowed.

A quick task is a build that leaves no task resource behind. You get the build, the logs, and the pushed image; you do not get anything you can trigger later. That is the whole difference between az acr build and az acr task create, and it is why the tutorials use a quick task to seed a base image and a task to react to it.

What you point it at

The positional argument is the context. The documented context locations^[1] are a local file-system directory, a GitHub repository (optionally narrowed to a branch, a subfolder, or a commit hash), an Azure DevOps repository subfolder, a remote tarball on a web server, and an OCI artifact already in a container registry. A local directory is packed into a tar file and uploaded, which is the line you see first in the output.

Two details about a local context surprise people. The .git folder is excluded from the uploaded package by default^[3], and a .dockerignore file containing !.git/** is what restores it; the same behaviour applies to az acr run. And -f/--file is the path of the Dockerfile relative to the source-code root folder^[4], defaulting to Dockerfile, so a repository holding Dockerfile-app and Dockerfile-base side by side is normal rather than exotic.

The context, the Dockerfile path, and the platform come together in the form you would actually type.

Listing 1: a quick task that builds an Arm64 image without publishing it

# --image/-t names the image; {{.Run.ID}} makes each build's tag unique.
# --file/-f is relative to the context root, not to your shell's directory.
# --platform takes OS/architecture/variant; the default is Linux on AMD64.
# --no-push compiles for validation only and leaves the registry untouched.
az acr build \
  --registry myregistry \
  --image samples/api:{{.Run.ID}} \
  --file docker/Dockerfile-app \
  --platform Linux/arm64/v8 \
  --no-push \
  .
# ... other optional arguments (--build-arg, --secret-build-arg, --target) omitted

The --image value above uses {{.Run.ID}}, one of the run variables covered with multi-step tasks below. It gives every build a tag that no other build reuses; why that matters for what you deploy is the unique-tag discussion on the ACR image management page.

Push is the default, and that is a quick-task property

az acr build pushes the built image to the registry when the build succeeds, and --no-push is a flag you add to prevent it^[4]. Remember which way round that default runs, because the multi-step build step behaves the opposite way.

Three more flags worth recognising

--build-arg sets build-time variables and its value is visible to the ACR team for debugging, so --secret-build-arg is the one for anything sensitive. --platform accepts OS, OS/architecture, or OS/architecture/variant; Linux images can target AMD64, ARM, ARM64, and 386, while Windows images are AMD64 only.

A quick task is also the shape a continuous-integration system uses. Sign in with a service principal via az login^[1] and the pipeline can issue az acr build commands directly, which is a smaller moving part than installing and authenticating a Docker daemon on every build agent. A quick task is the whole build compressed into one command: the only decisions it asks of you are the context, the Dockerfile, the platform, and whether to publish.

The commit trigger is the first reason to create a task instead of running a quick build: you want the rebuild to happen without anyone typing anything. Creating the task with a Git context is all it takes, because the commit trigger is enabled by default^[5] and ACR registers the repository webhook for you.

Here is that task, with every trigger flag deliberately left at its default.

Listing 2: a task that rebuilds on every commit to one branch

# --context pins the source: repository, then #branch, then :subfolder.
# --git-access-token lets ACR create the webhook and read the repo.
# No trigger flag appears here: commit is on by default with a Git context.
az acr task create \
  --registry myregistry \
  --name taskhelloworld \
  --image helloworld:{{.Run.ID}} \
  --context https://github.com/myorg/acr-build-helloworld-node.git#main:src \
  --file Dockerfile \
  --git-access-token $GIT_PAT
# ... --schedule and --assign-identity omitted; both are covered below

The context fragment is a filter, not a comment

The #main:src fragment on --context binds the task to one branch and one subfolder^[6]. A commit to a different branch reaches the webhook and starts nothing, which is what the figure below shows as the dead-end path. That is a feature in a monorepo and a mystery when it is unintentional, so when a task appears not to fire, compare the branch you pushed with the branch in the task's --context. A commit that does fire it shows Commit in the TRIGGER column of az acr task list-runs.

The token the webhook needs

ACR needs a credential from your Git host, a personal access token (PAT), to set the webhook^[1] in the repository. A personal access token is one your Git host issues on behalf of your account and scopes to a list of permissions, and the webhook it buys is registered in the Git repository, not on the registry. The required scopes are exactly these:

Microsoft also warns that anything on the command line or in a URI may be logged in ACR diagnostic tracing^[1], naming personal access tokens explicitly, which is a reason to pass the token from a variable rather than pasting it.

Commit and pull request are two different triggers

On a Git context, ACR Tasks supports a Commit trigger, enabled by default, and a Pull request trigger, disabled by default^[5] and turned on with --pull-request-trigger-enabled true. Treat any statement that a commit trigger also covers pull requests as false.

Which Git service you use decides whether automation is available at all. The FAQ's support matrix^[3] lists GitHub and Azure Repos as supporting both manual builds and auto-build through the commit trigger, while GitLab and Bitbucket work as a source context for manual builds only. GitHub Enterprise repositories support neither commit nor pull-request triggers.

Once the task exists, az acr task run --registry myregistry --name taskhelloworld starts it immediately, independent of any trigger. Do that once before trusting the automation: it proves the definition builds, and it is also the step that registers base-image tracking, which the next section turns into a trigger of its own.

This trigger is the reason ACR Tasks exists as more than a remote docker build. A base image is the parent image a Dockerfile's FROM instruction names^[7], typically carrying the operating system and sometimes a framework, and it is where OS and framework security patches arrive. When the maintainer republishes it, every application image built on top of it is stale until someone rebuilds it. The base-image-update trigger is what makes that rebuild automatic.

Tracking is discovered, never declared

ACR Tasks dynamically discovers base-image dependencies while it builds an image, which is the dependency block printed at the end of a run. Two consequences follow, and both are exam-grade.

First, a task tracks nothing until it has built successfully at least once, so you must trigger it once^[7], typically with az acr task run. The base-image tutorial does exactly this: it creates the task, runs it manually so the dependency is recorded^[8], and only then patches the base image.

Second, tracking is not something you write in the task definition. There is no list of base images to maintain; there is a trigger you leave on or turn off, and --base-image-trigger-enabled is True by default^[5] on every task created with az acr task create.

Where the base image has to live, and what it has to be tagged

Detection covers four locations, and this list is exhaustive: the same Azure container registry the task runs in, another private Azure container registry in the same or a different region, a public repository in Docker Hub, and a public repository in the Microsoft Container Registry (MCR). If the FROM image sits in one of those, ACR adds a hook so the image is rebuilt whenever its base is updated.

The tag matters as much as the location. To trigger a task on a base-image update the base must have a stable tag, such as node:9-alpine, because a stable tag is the one that gets re-pointed at each serviced release. A base republished under a brand-new version tag does not trigger a task: nothing your Dockerfile refers to changed. Pinning FROM by digest is the same situation taken to its limit, since a digest names fixed content that cannot be re-pointed at all. A stable tag is also exactly what the ACR image management page tells you not to deploy from, and both rules hold at once: a base image is meant to roll forward so the images built on it inherit patches, while a deployment is meant to stay put^[9] so a restart cannot pull something different from its peers. Keep the stable tag in FROM, and a unique tag on what you deploy.

How quickly it fires

The delay depends on where the base lives, and the figure below shows both paths. For a base image in an Azure container registry, in the same registry or any other, the task is triggered immediately^[7]. For a base image in a public Docker Hub or MCR repository, ACR Tasks checks for updates at a random interval of between 10 and 60 minutes, and dependent tasks run after that check. Either way the rebuild shows Image Update in the TRIGGER column. This is one of the practical arguments for Microsoft's recommendation to copy public base content into your own registry and build FROM the private copy.

One documented blind spot

An ACR task only tracks base-image updates for application, or runtime, images. It does not track base-image updates for the intermediate buildtime images of a multi-stage Dockerfile. A multi-stage build whose first stage compiles against a patched SDK image will not rebuild on that SDK's update; only the base of the final runtime stage is tracked. Matching that, --base-image-trigger-type defaults to Runtime.

Taken together: leave the trigger on, run the task once, keep FROM pointing at a stable tag in a tracked registry, and OS patching becomes something the registry does rather than something a person remembers.

A timer trigger runs a task on a fixed schedule and reacts to nothing else. It is the right answer when the requirement is periodic ("every night", "every weekday at noon") and the wrong answer when the requirement is causal ("when the base image is patched"), because a schedule can only shorten the window between an event and the rebuild, never close it.

Add one at creation time with --schedule and a cron expression, and note that a scheduled task does not need source code at all^[10]: passing --context /dev/null with --cmd gives you a container that runs on a timer, which is how registry maintenance work is usually shaped.

Listing 3: a nightly task with no source context

# --cmd runs a container instead of building an image.
# --context /dev/null means there is no source code to fetch.
# --schedule is a five-field cron expression, always interpreted as UTC.
az acr task create \
  --registry myregistry \
  --name timertask \
  --cmd mcr.microsoft.com/hello-world \
  --context /dev/null \
  --schedule "0 21 * * *"

The cron dialect, precisely

ACR Tasks interprets cron expressions with the NCronTab library, and supported expressions have five required fields separated by white space^[10]: {minute} {hour} {day} {month} {day-of-week}. Three rules cover most mistakes:

• The time zone is always Coordinated Universal Time (UTC) and hours are in 24-hour format. "0 12 * * Mon-Fri" is noon UTC on weekdays, whatever your own clock says.
• The {second} and {year} fields are not supported. An expression copied from a system that uses six or seven fields has to have them removed.
• Frequencies of up to once per minute are supported, so "*/5 * * * *" (every five minutes) is fine and sub-minute scheduling does not exist.

Days of week are 0 to 6 starting at Sunday, and names such as Monday or the recommended three-letter Mon work too, case-insensitively.

More than one timer, and timers beside other triggers

A task may carry several timer triggers as long as their schedules differ, and they can be named for easier management or left to take a default name. If two schedules coincide, ACR Tasks triggers the task once for each timer. After creation, az acr task timer add, update, list, and remove manage them individually.

Triggers are not exclusive, which does not undo the rule this section opened with: the timer itself still reacts to nothing but the clock, while the task it is attached to can carry the commit and base-image triggers alongside it. az acr task show --output table prints the enabled set in a TRIGGERS column, which is the quickest way to see that a task you thought was schedule-only also reports BASE_IMAGE. The base-image trigger being on by default is exactly how that happens.

The canonical scheduled workload is registry maintenance. A cmd step running the acr image alias can list and purge old tags on a nightly schedule, using the acr purge command^[11] inside the task. What purge actually deletes, and the digest-pinning warning attached to it, is covered on the ACR image management page; the timer trigger is only the clock that starts it. The line to carry out of this section: a timer answers how often, never in response to what.

One image built and pushed is the single-step case. A multi-step task replaces it with a series of steps in a YAML file^[12], each of which builds an image, pushes images, or runs a container, and each of which uses a container as its execution environment. That is what makes build, test, then publish possible inside one run instead of across three systems.

Three step types, and the push that is not automatic

• build builds a container image using familiar docker build syntax, taking -t for the image name and tag, -f for the Dockerfile, and a context.
• push pushes built or retagged images to a registry, given a collection of image references.
• cmd runs a container as a command, passing parameters to its ENTRYPOINT, which is how unit and functional tests execute inside a run.

The reference is explicit that unlike az acr build, running ACR Tasks does not provide default push behaviour^[11]: the default assumption is build, validate, then push. An image built by a build step and never named in a push step exists only for the duration of the run, which is exactly what you want for a test image and exactly what surprises you if you expected the quick-task default.

Ordering: sequential by default, when for anything else

Give a step an id and other steps can name it. The when property then controls execution: when: ["-"] declares no dependency, so the step starts immediately and runs concurrently with other such steps, while when: ["id1", "id2"] holds the step until both named steps finish. If a step has no when at all, it depends on the previous step in the file, which is why a simple two-line build-and-push YAML works without any dependency wiring.

The figure below draws the dependency graph of the worked example: build-app and build-tests start together, run-app follows the first of them, tests runs against the running container, and push happens only after tests succeeds.

Variables instead of hard-coded names

Run variables are available to steps as {{.Run.VariableName}}, and as of YAML version v1.1.0 most have a shorter alias used with a $ prefix. The ones that matter in practice are Run.ID ($ID), the unique identifier of the current run and the usual source of a unique image tag; Run.Registry ($Registry), the fully qualified login server of the registry the task is running in; Run.RegistryName ($RegistryName) for steps that want the bare name; and Run.Commit and Run.Branch, populated for a task triggered by a commit to a GitHub repository. Writing $Registry/hello-world:$ID instead of myregistry.azurecr.io/hello-world:v1 is what lets the same YAML file run in any registry. A value can also be supplied at run time: a placeholder such as {{.Values.tag}} is filled by az acr task run --set tag=v2.

The two timeouts

Two different timeouts apply, and confusing them wastes an afternoon. The step timeout is the maximum number of seconds one step may run, defaulting to 600 (10 minutes), settable per step as timeout or for all steps as the task-level stepTimeout. The run timeout is a property of the task itself, set with --timeout on az acr task create and defaulting to 3600 seconds^[5]; if it is smaller than the sum of the step timeouts, it takes priority.

Credentials without a secret in the file

A task can carry a managed identity, which is an identity in Microsoft Entra ID that Azure manages for the resource^[13] so no credentials appear in the task steps. Enable a system-assigned identity by passing --assign-identity with no value, or a user-assigned one by passing the identity's resource ID, then grant that identity a role on whatever the task must reach: pull or push on another registry, or read access on a key vault. A secrets block can then reference a Key Vault secret URL, and az acr task credential add --use-identity attaches the identity to another registry's login server.

A multi-step file runs on demand with az acr run --registry myregistry -f acr-task.yaml <context>, or becomes a task with az acr task create -f acr-task.yaml, at which point every trigger in this page applies to it unchanged.

Questions on this objective are almost always a scenario plus a requirement verb, and the verb selects the mechanism. Read for the event first.

"...without installing Docker" / "...from Cloud Shell" / "...offload the build". The answer is az acr build, a quick task. Distractors that install a container runtime on a build agent or push from a developer workstation are solving a problem the service already removed.

"...automatically when developers commit". A task created with a Git context. Watch for two traps in the options: an answer that claims the commit trigger also covers pull requests (a separate trigger, off by default), and an answer built on GitLab or Bitbucket, which support manual builds but no commit trigger.

"...whenever the base OS image is patched" / "...keep application images current with framework updates". The base-image-update trigger, which needs no configuration beyond leaving it enabled. The strongest distractor is a schedule; the correct reasoning is that a timer is periodic and the requirement is causal. If the scenario mentions a Dockerfile that pins FROM by digest, or a base whose new release carries a new version tag, or a base image used only by an early stage of a multi-stage build, then no rebuild happens and the option promising one is wrong.

"...nothing happened when the base image was updated". Check whether the task has ever run. Dependencies are discovered during a build, so a task created but never run tracks nothing.

"...every night at 02:00" / "...periodic cleanup". A timer trigger with a five-field UTC cron expression. An option offering "0 2 * * * *" has a seconds or year field that ACR Tasks does not accept.

"...run tests against the image and publish only if they pass". A multi-step task. The discriminator is that the YAML build step does not push, so the correct answer includes an explicit push step gated with when.

"...which run started this build". az acr task list-runs and its TRIGGER column: Manual, Commit, Image Update, or Timer. A question that describes the evidence rather than the configuration is asking you to read that column backwards to the trigger.

One last discrimination that catches people out: az acr build and az acr task run both start a build immediately and both appear as Manual, but only the second one exercises a saved task definition with its triggers, its context, and its image name. Testing a task means az acr task run; building an image once means az acr build.