ACR Tasks reference: YAML

Multi-step task definition in ACR Tasks provides a container-centric compute primitive focused on building, testing, and patching containers. This article covers the commands, parameters, properties, and syntax for the YAML files that define your multi-step tasks.

This article contains reference for creating multi-step task YAML files for ACR Tasks. If you'd like an introduction to ACR Tasks, see the ACR Tasks overview.

acr-task.yaml file format

ACR Tasks supports multi-step task declaration in standard YAML syntax. You define a task's steps in a YAML file. You can then run the task manually by passing the file to the az acr run command. Or, use the file to create a task with az acr task create that's triggered automatically on a Git commit, a base image update, or a schedule. Although this article refers to acr-task.yaml as the file containing the steps, ACR Tasks supports any valid filename with a supported extension.

The top-level acr-task.yaml primitives are task properties, step types, and step properties:

  • Task properties apply to all steps throughout task execution. There are several global task properties, including:
    • version
    • stepTimeout
    • workingDirectory
  • Task step types represent the types of actions that can be performed in a task. There are three step types:
    • build
    • push
    • cmd
  • Task step properties are parameters that apply to an individual step. There are several step properties, including:
    • startDelay
    • timeout
    • when
    • ...and many more.

The base format of an acr-task.yaml file, including some common step properties, follows. While not an exhaustive representation of all available step properties or step type usage, it provides a quick overview of the basic file format.

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

Supported task filename extensions

ACR Tasks has reserved several filename extensions, including .yaml, that it will process as a task file. Any extension not in the following list is considered by ACR Tasks to be a Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML is the only file format currently supported by ACR Tasks. The other filename extensions are reserved for possible future support.

Run the sample tasks

There are several sample task files referenced in the following sections of this article. The sample tasks are in a public GitHub repository, Azure-Samples/acr-tasks. You can run them with the Azure CLI command az acr run. The sample commands are similar to:

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

The formatting of the sample commands assumes you've configured a default registry in the Azure CLI, so they omit the --registry parameter. To configure a default registry, use the az config command with the set command, which accepts an defaults.acr=REGISTRY_NAME key value pair.

For example, to configure the Azure CLI with a default registry named "myregistry":

az config set defaults.acr=myregistry

Task properties

Task properties typically appear at the top of an acr-task.yaml file, and are global properties that apply throughout the full execution of the task steps. Some of these global properties can be overridden within an individual step.

Property Type Optional Description Override supported Default value
version string Yes The version of the acr-task.yaml file as parsed by the ACR Tasks service. While ACR Tasks strives to maintain backward compatibility, this value allows ACR Tasks to maintain compatibility within a defined version. If unspecified, defaults to v1.0.0. N/A v1.0.0
stepTimeout int (seconds) Yes The maximum number of seconds a step can run. If the stepTimeout property is specified on a task, it sets the default timeout property of all the steps. If the timeout property is specified on a step, it overrides the stepTimeout property provided by the task.

The sum of the step timeout values for a task should equal the value of the task's run timeout property (for example, set by passing --timeout to the az acr task create command). If the tasks's run timeout value is smaller, it takes priority.
Yes 600 (10 minutes)
workingDirectory string Yes The working directory of the container during runtime. If the property is specified on a task, it sets the default workingDirectory property of all the steps. If specified on a step, it overrides the property provided by the task. Yes c:\workspace in Windows or /workspace in Linux
env [string, string, ...] Yes Array of strings in key=value format that define the environment variables for the task. If the property is specified on a task, it sets the default env property of all the steps. If specified on a step, it overrides any environment variables inherited from the task. Yes None
secrets [secret, secret, ...] Yes Array of secret objects. No None
networks [network, network, ...] Yes Array of network objects. No None
volumes [volume, volume, ...] Yes Array of volume objects. Specifies volumes with source content to mount to a step. No None

secret

The secret object has the following properties.

Property Type Optional Description Default value
id string No The identifier of the secret. None
keyvault string Yes The Azure Key Vault Secret URL. None
clientID string Yes The client ID of the user-assigned managed identity for Azure resources. None

network

The network object has the following properties.

Property Type Optional Description Default value
name string No The name of the network. None
driver string Yes The driver to manage the network. None
ipv6 bool Yes Whether IPv6 networking is enabled. false
skipCreation bool Yes Whether to skip network creation. false
isDefault bool Yes Whether the network is a default network provided with Azure Container Registry. false

volume

The volume object has the following properties.

Property Type Optional Description Default value
name string No The name of the volume to mount. Can contain only alphanumeric characters, '-', and '_'. None
secret map[string]string No Each key of the map is the name of a file created and populated in the volume. Each value is the string version of the secret. Secret values must be Base64 encoded. None

Task step types

ACR Tasks supports three step types. Each step type supports several properties, detailed in the section for each step type.

Step type Description
build Builds a container image using familiar docker build syntax.
push Executes a docker push of newly built or retagged images to a container registry. Azure Container Registry, other private registries, and the public Docker Hub are supported.
cmd Runs a container as a command, with parameters passed to the container's [ENTRYPOINT]. The cmd step type supports parameters like env, detach, and other familiar docker run command options, enabling unit and functional testing with concurrent container execution.

build

Build a container image. The build step type represents a multi-tenant, secure means of running docker build in the cloud as a first-class primitive.

Syntax: build

version: v1.1.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

Run the az acr runcommand to get the docker version.

az acr run -r $ACR_NAME --cmd "docker version" /dev/null

Add environment variable DOCKER_BUILDKIT=1 in yaml file to enable buildkit and use secret with buildkit.

The build step type supports the parameters in the following table. The build step type also supports all build options of the docker build command, such as --build-arg to set build-time variables.

Parameter Description Optional
-t | --image Defines the fully qualified image:tag of the built image.

As images may be used for inner task validations, such as functional tests, not all images require push to a registry. However, to instance an image within a Task execution, the image does need a name to reference.

Unlike az acr build, running ACR Tasks doesn't provide default push behavior. With ACR Tasks, the default scenario assumes the ability to build, validate, then push an image. See push for how to optionally push built images.
Yes
-f | --file Specifies the Dockerfile passed to docker build. If not specified, the default Dockerfile in the root of the context is assumed. To specify a Dockerfile, pass the filename relative to the root of the context. Yes
context The root directory passed to docker build. The root directory of each task is set to a shared workingDirectory, and includes the root of the associated Git cloned directory. No

Properties: build

The build step type supports the following properties. Find details of these properties in the Task step properties section of this article.

Properties Type Required
detach bool Optional
disableWorkingDirectoryOverride bool Optional
entryPoint string Optional
env [string, string, ...] Optional
expose [string, string, ...] Optional
id string Optional
ignoreErrors bool Optional
isolation string Optional
keep bool Optional
network object Optional
ports [string, string, ...] Optional
pull bool Optional
repeat int Optional
retries int Optional
retryDelay int (seconds) Optional
secret object Optional
startDelay int (seconds) Optional
timeout int (seconds) Optional
volumeMount object Optional
when [string, string, ...] Optional
workingDirectory string Optional

Examples: build

Build image - context in root

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git
version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

Build image - context in subdirectory

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

Dynamic variable passing in ACR Tasks

When working with Azure container registry (ACR) tasks, you may find yourself needing to pass different values to your build process without changing the task definition by using the --set flag with the az acr task run command.

Example: Setting image tag at runtime

Suppose you have an ACR task defined in a acr-task.yml file with a placeholder for the image tag:

steps:
  - build: -t $Registry/hello-world:{{.Values.tag}}

You can trigger the task and set the tag variable to v2 at runtime using the following Azure CLI command:

az acr task run --registry myregistry --name mytask --set tag=v2

This command will start the ACR task named mytask and build the image using the v2 tag, overriding the placeholder in the acr-task.yml file.

This approach allows for customization in your CI/CD pipelines, enabling you to dynamically adjust parameters based on your current needs without altering the task definitions.

push

Push one or more built or retagged images to a container registry. Supports pushing to private registries like Azure Container Registry, or to the public Docker Hub.

Syntax: push

The push step type supports a collection of images. YAML collection syntax supports inline and nested formats. Pushing a single image is typically represented using inline syntax:

version: v1.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

For increased readability, use nested syntax when pushing multiple images:

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $Registry/hello-world:latest

Properties: push

The push step type supports the following properties. Find details of these properties in the Task step properties section of this article.

Property Type Required
env [string, string, ...] Optional
id string Optional
ignoreErrors bool Optional
startDelay int (seconds) Optional
timeout int (seconds) Optional
when [string, string, ...] Optional

Examples: push

Push multiple images

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

Build, push, and run

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push:
    - $Registry/hello-world:$ID
  - cmd: $Registry/hello-world:$ID

cmd

The cmd step type runs a container.

Syntax: cmd

version: v1.1.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

Properties: cmd

The cmd step type supports the following properties:

Property Type Required
detach bool Optional
disableWorkingDirectoryOverride bool Optional
entryPoint string Optional
env [string, string, ...] Optional
expose [string, string, ...] Optional
id string Optional
ignoreErrors bool Optional
isolation string Optional
keep bool Optional
network object Optional
ports [string, string, ...] Optional
pull bool Optional
repeat int Optional
retries int Optional
retryDelay int (seconds) Optional
secret object Optional
startDelay int (seconds) Optional
timeout int (seconds) Optional
volumeMount object Optional
when [string, string, ...] Optional
workingDirectory string Optional

You can find details of these properties in the Task step properties section of this article.

Examples: cmd

Run hello-world image

This command executes the hello-world.yaml task file, which references the hello-world image on Docker Hub.

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  - cmd: mcr.microsoft.com/hello-world

Run bash image and echo "hello world"

This command executes the bash-echo.yaml task file, which references the bash image on Docker Hub.

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  - cmd: bash echo hello world

Run specific bash image tag

To run a specific image version, specify the tag in the cmd.

This command executes the bash-echo-3.yaml task file, which references the bash:3.0 image on Docker Hub.

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  - cmd: bash:3.0 echo hello world

Run custom images

The cmd step type references images using the standard docker run format. Images not prefaced with a registry are assumed to originate from docker.io. The previous example could equally be represented as:

version: v1.1.0
steps:
  - cmd: docker.io/bash:3.0 echo hello world

By using the standard docker run image reference convention, cmd can run images from any private registry or the public Docker Hub. If you're referencing images in the same registry in which ACR Task is executing, you don't need to specify any registry credentials.

  • Run an image that's from an Azure container registry. The following example assumes you have a registry named myregistry, and a custom image myimage:mytag.

    version: v1.1.0
    steps:
        - cmd: myregistry.azurecr.io/myimage:mytag
    
  • Generalize the registry reference with a Run variable or alias

    Instead of hard-coding your registry name in an acr-task.yaml file, you can make it more portable by using a Run variable or alias. The Run.Registry variable or $Registry alias expands at runtime to the name of the registry in which the task is executing.

    For example, to generalize the preceding task so that it works in any Azure container registry, reference the $Registry variable in the image name:

    version: v1.1.0
    steps:
      - cmd: $Registry/myimage:mytag
    

Access secret volumes

The volumes property allows volumes and their secret contents to be specified for build and cmd steps in a task. Inside each step, an optional volumeMounts property lists the volumes and corresponding container paths to mount into the container at that step. Secrets are provided as files at each volume's mount path.

Execute a task and mount two secrets to a step: one stored in a key vault and one specified on the command line:

az acr run -f mounts-secrets.yaml --set-secret mysecret=abcdefg123456 https://github.com/Azure-Samples/acr-tasks.git
# This template demonstrates mounting a custom volume into a container at a CMD step
secrets:
  - id: sampleSecret
    keyvault: https://myacbvault2.vault.azure.net/secrets/SampleSecret # Replace with valid keyvault with access

volumes:
  - name: mysecrets
    secret:
      mysecret1: {{.Secrets.sampleSecret | b64enc}}
      mysecret2: {{.Values.mysecret | b64enc}}

steps:
  - cmd: bash cat /run/test/mysecret1 /run/test/mysecret2
    volumeMounts:
      - name: mysecrets
        mountPath: /run/test

Task step properties

Each step type supports several properties appropriate for its type. The following table defines all of the available step properties. Not all step types support all properties. To see which of these properties are available for each step type, see the cmd, build, and push step type reference sections.

Property Type Optional Description Default value
detach bool Yes Whether the container should be detached when running. false
disableWorkingDirectoryOverride bool Yes Whether to disable workingDirectory override functionality. Use this in combination with workingDirectory to have complete control over the container's working directory. false
entryPoint string Yes Overrides the [ENTRYPOINT] of a step's container. None
env [string, string, ...] Yes Array of strings in key=value format that define the environment variables for the step. None
expose [string, string, ...] Yes Array of ports that are exposed from the container. None
id string Yes Uniquely identifies the step within the task. Other steps in the task can reference a step's id, such as for dependency checking with when.

The id is also the running container's name. Processes running in other containers in the task can refer to the id as its DNS host name, or for accessing it with docker logs [id], for example.
acb_step_%d, where %d is the 0-based index of the step top-down in the YAML file
ignoreErrors bool Yes Whether to mark the step as successful regardless of whether an error occurred during container execution. false
isolation string Yes The isolation level of the container. default
keep bool Yes Whether the step's container should be kept after execution. false
network object Yes Identifies a network in which the container runs. None
ports [string, string, ...] Yes Array of ports that are published from the container to the host. None
pull bool Yes Whether to force a pull of the container before executing it to prevent any caching behavior. false
privileged bool Yes Whether to run the container in privileged mode. false
repeat int Yes The number of retries to repeat the execution of a container. 0
retries int Yes The number of retries to attempt if a container fails its execution. A retry is only attempted if a container's exit code is non-zero. 0
retryDelay int (seconds) Yes The delay in seconds between retries of a container's execution. 0
secret object Yes Identifies an Azure Key Vault secret or managed identity for Azure resources. None
startDelay int (seconds) Yes Number of seconds to delay a container's execution. 0
timeout int (seconds) Yes Maximum number of seconds a step may execute before being terminated. 600
when [string, string, ...] Yes Configures a step's dependency on one or more other steps within the task. None
user string Yes The user name or UID of a container None
workingDirectory string Yes Sets the working directory for a step. By default, ACR Tasks creates a root directory as the working directory. However, if your build has several steps, earlier steps can share artifacts with later steps by specifying the same working directory. c:\workspace in Windows or /workspace in Linux

volumeMount

The volumeMount object has the following properties.

Property Type Optional Description Default value
name string No The name of the volume to mount. Must exactly match the name from a volumes property. None
mountPath string no The absolute path to mount files in the container. None

Examples: Task step properties

Example: id

Build two images, instancing a functional test image. Each step is identified by a unique id which other steps in the task reference in their when property.

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Example: when

The when property specifies a step's dependency on other steps within the task. It supports two parameter values:

  • when: ["-"] - Indicates no dependency on other steps. A step specifying when: ["-"] will begin execution immediately, and enables concurrent step execution.
  • when: ["id1", "id2"] - Indicates the step is dependent upon steps with id "id1" and id "id2". This step won't be executed until both "id1" and "id2" steps complete.

If when isn't specified in a step, that step is dependent on completion of the previous step in the acr-task.yaml file.

Sequential step execution without when:

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

Sequential step execution with when:

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

Parallel images build:

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

Parallel image build and dependent testing:

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git
version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Run variables

ACR Tasks includes a default set of variables that are available to task steps when they execute. These variables can be accessed by using the format {{.Run.VariableName}}, where VariableName is one of the following:

  • Run.ID
  • Run.SharedVolume
  • Run.Registry
  • Run.RegistryName
  • Run.Date
  • Run.OS
  • Run.Architecture
  • Run.Commit
  • Run.Branch
  • Run.TaskName

The variable names are generally self-explanatory. Details follow for commonly used variables. As of YAML version v1.1.0, you can use an abbreviated, predefined task alias in place of most run variables. For example, in place of {{.Run.Registry}}, use the $Registry alias.

Run.ID

Each Run, through az acr run, or trigger based execution of tasks created through az acr task create, has a unique ID. The ID represents the Run currently being executed.

Typically used for a uniquely tagging an image:

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$ID .

Run.SharedVolume

The unique identifier for a shared volume that is accessible by all task steps. The volume is mounted to c:\workspace in Windows or /workspace in Linux.

Run.Registry

The fully qualified server name of the registry. Typically used to generically reference the registry where the task is being run.

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

Run.RegistryName

The name of the container registry. Typically used in task steps that don't require a fully qualified server name, for example, cmd steps that run Azure CLI commands on registries.

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.Date

The current UTC time the run began.

Run.Commit

For a task triggered by a commit to a GitHub repository, the commit identifier.

Run.Branch

For a task triggered by a commit to a GitHub repository, the branch name.

Aliases

As of v1.1.0, ACR Tasks supports aliases that are available to task steps when they execute. Aliases are similar in concept to aliases (command shortcuts) supported in bash and some other command shells.

With an alias, you can launch any command or group of commands (including options and filenames) by entering a single word.

ACR Tasks supports several predefined aliases and also custom aliases you create.

Predefined aliases

The following task aliases are available to use in place of run variables:

Alias Run variable
ID Run.ID
SharedVolume Run.SharedVolume
Registry Run.Registry
RegistryName Run.RegistryName
Date Run.Date
OS Run.OS
Architecture Run.Architecture
Commit Run.Commit
Branch Run.Branch

In task steps, precede an alias with the $ directive, as in this example:

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

Image aliases

Each of the following aliases points to a stable image in Microsoft Container Registry (MCR). You can refer to each of them in the cmd section of a Task file without using a directive.

Alias Image
acr mcr.microsoft.com/acr/acr-cli:0.5
az mcr.microsoft.com/acr/azure-cli:7ee1d7f
bash mcr.microsoft.com/acr/bash:7ee1d7f
curl mcr.microsoft.com/acr/curl:7ee1d7f

The following example task uses several aliases to purge image tags older than 7 days in the repo samples/hello-world in the run registry:

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

Custom alias

Define a custom alias in your YAML file and use it as shown in the following example. An alias can contain only alphanumeric characters. The default directive to expand an alias is the $ character.

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

You can link to a remote or local YAML file for custom alias definitions. The following example links to a YAML file in Azure blob storage:

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

Next steps

For an overview of multi-step tasks, see the Run multi-step build, test, and patch tasks in ACR Tasks.

For single-step builds, see the ACR Tasks overview.