az acr task

Manage a collection of steps for building, testing and OS & Framework patching container images using Azure Container Registries.

Commands

az acr task cancel-run

Cancel a specified run of an Azure Container Registry.

az acr task create

Create a series of steps for building, testing and OS & Framework patching containers. Tasks support triggers from git commits and base image updates.

az acr task credential

Manage credentials for a task. Please see https://aka.ms/acr/tasks/cross-registry-authentication for more information.

az acr task credential add

Add a custom registry login credential to the task.

az acr task credential list

List all the custom registry credentials for task.

az acr task credential remove

Remove credential for a task.

az acr task credential update

Update the registry login credential for a task.

az acr task delete

Delete a task from an Azure Container Registry.

az acr task identity

Managed Identities for Task. Please see https://aka.ms/acr/tasks/task-create-managed-identity for more information.

az acr task identity assign

Update the managed identity for a task.

az acr task identity remove

Remove managed identities for a task.

az acr task identity show

Display the managed identities for task.

az acr task list

List the tasks for an Azure Container Registry.

az acr task list-runs

List all of the executed runs for an Azure Container Registry, with the ability to filter by a specific Task.

az acr task logs

Show logs for a particular run. If no run-id is supplied, show logs for the last created run.

az acr task run

Manually trigger a task that might otherwise be waiting for git commits or base image update triggers.

az acr task show

Get the properties of a named task for an Azure Container Registry.

az acr task show-run

Get the properties of a specified run of an Azure Container Registry Task.

az acr task timer

Manage timer triggers for a task.

az acr task timer add

Add a timer trigger to a task.

az acr task timer list

List all timer triggers for a task.

az acr task timer remove

Remove a timer trigger from a task.

az acr task timer update

Update the timer trigger for a task.

az acr task update

Update a task for an Azure Container Registry.

az acr task update-run

Patch the run properties of an Azure Container Registry Task.

az acr task cancel-run

Cancel a specified run of an Azure Container Registry.

az acr task cancel-run --registry
                       --run-id
                       [--resource-group]
                       [--subscription]

Examples

Cancel a run

az acr task cancel-run -r MyRegistry --run-id runId

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

--run-id

The unique run identifier.

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az acr task create

Create a series of steps for building, testing and OS & Framework patching containers. Tasks support triggers from git commits and base image updates.

az acr task create --context
                   --name
                   --registry
                   [--agent-pool]
                   [--arg]
                   [--assign-identity]
                   [--auth-mode {Default, None}]
                   [--base-image-trigger-enabled {false, true}]
                   [--base-image-trigger-name]
                   [--base-image-trigger-type {All, Runtime}]
                   [--cmd]
                   [--commit-trigger-enabled {false, true}]
                   [--cpu]
                   [--file]
                   [--git-access-token]
                   [--image]
                   [--no-cache {false, true}]
                   [--no-push {false, true}]
                   [--platform]
                   [--pull-request-trigger-enabled {false, true}]
                   [--resource-group]
                   [--schedule]
                   [--secret-arg]
                   [--set]
                   [--set-secret]
                   [--source-trigger-name]
                   [--status {Disabled, Enabled}]
                   [--subscription]
                   [--target]
                   [--timeout]
                   [--update-trigger-endpoint]
                   [--update-trigger-payload-type {Default, Token}]
                   [--values]

Examples

Create a task without the source location.

az acr task create -n hello-world -r MyRegistry --cmd '$Registry/myimage' -c /dev/null

Create a task with the definition from the standard input and with a timer trigger that runs the task at the top of every hour using the default trigger name. Either 'Ctrl + Z'(Windows) or 'Ctrl + D'(Linux) terminates the input stream.

cat task.yaml | az acr task create -n hello-world -r MyRegistry -f - -c /dev/null \
    --schedule "0 */1 * * *"
az acr task create -n hello-world -r MyRegistry -f - -c /dev/null --schedule "0 */1 * * *"

Create a Linux task from a public GitHub repository which builds the hello-world image without triggers and uses a build argument.

az acr task create -t hello-world:{{.Run.ID}} -n hello-world -r MyRegistry \
    -c https://github.com/Azure/acr-builder.git -f Dockerfile \
    --commit-trigger-enabled false --base-image-trigger-enabled false \
    --arg DOCKER_CLI_BASE_IMAGE=docker:18.03.0-ce-git

Create a Linux task using a specific branch of a private Azure DevOps repository which builds the hello-world image on Arm architecture (V7 variant) and has triggers enabled.

az acr task create -t hello-world:{{.Run.ID}} -n hello-world -r MyRegistry \
    -c https://msazure.visualstudio.com/DefaultCollection/Project/_git/Repo#Branch:Folder \
    -f Dockerfile --git-access-token <Personal Access Token> --platform linux/arm/v7

Create a Linux task from a public GitHub repository which builds the hello-world image with both a git commit and pull request trigger enabled. Note that this task does not use Source Registry (MyRegistry), so we can explicitly set Auth mode as None for it.

az acr task create -t hello-world:{{.Run.ID}} -n hello-world -r MyRegistry  -f Dockerfile \
    --auth-mode None -c https://github.com/Azure-Samples/acr-build-helloworld-node.git \
    --pull-request-trigger-enabled true --git-access-token 000000000000000000000000000000000

Create a Windows task from a public GitHub repository which builds the Azure Container Builder image on Amd64 architecture with only base image trigger enabled.

az acr task create -t acb:{{.Run.ID}} -n acb-win -r MyRegistry \
    -c https://github.com/Azure/acr-builder.git -f Windows.Dockerfile \
    --commit-trigger-enabled false --platform Windows/amd64

Create a Linux multi-step task from a public GitHub repository with with both system-assigned and user-assigned managed identities and base image, git commit, pull request, and timer triggers that run the task at noon on Mondays through Fridays with the timer trigger name provided.

az acr task create -t hello-world:{{.Run.ID}} -n hello-world -r MyRegistry \
    --pull-request-trigger-enabled true --schedule "dailyTimer:0 12 * * Mon-Fri" \
    -c https://github.com/Azure-Samples/acr-tasks.git#:multipleRegistries -f testtask.yaml \
    --assign-identity [system] "/subscriptions/<subscriptionId>/resourcegroups/<myResourceGroup>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<myUserAssignedIdentitiy>"

Required Parameters

--context -c

The full URL to the source code repository (Requires '.git' suffix for a github repo) or the repository of an OCI artifact in an Azure container registry (e.g., 'oci://myregistry.azurecr.io/myartifact:mytag'). If '/dev/null' is specified, the value will be set to None and ignored.

--name -n

The name of the task.

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--agent-pool

The name of the agent pool.

--arg

Build argument in '--arg name[=value]' format. Multiples supported by passing '--arg` multiple times.

--assign-identity

Assigns managed identities to the task. Use '[system]' to refer to the system-assigned identity or a resource ID to refer to a user-assigned identity. Please see https://aka.ms/acr/tasks/task-create-managed-identity for more information.

--auth-mode

Auth mode of the source registry.

accepted values: Default, None
--base-image-trigger-enabled

Indicates whether the base image trigger is enabled.

accepted values: false, true
default value: 1
--base-image-trigger-name

The name of the base image trigger.

default value: defaultBaseimageTriggerName
--base-image-trigger-type

The type of the auto trigger for base image dependency updates.

accepted values: All, Runtime
default value: Runtime
--cmd

Commands to execute.

--commit-trigger-enabled

Indicates whether the source control commit trigger is enabled.

accepted values: false, true
default value: 1
--cpu

The CPU configuration in terms of number of cores required for the run.

default value: 2
--file -f

Relative path of the the task/docker file to the source code root folder. Task files must be suffixed with '.yaml' or piped from the standard input using '-'.

--git-access-token

The access token used to access the source control provider.

--image -t

The name and tag of the image using the format: '-t repo/image:tag'. Multiple tags are supported by passing -t multiple times.

--no-cache

Indicates whether the image cache is enabled.

accepted values: false, true
--no-push

Indicates whether the image built should be pushed to the registry.

accepted values: false, true
--platform

The platform where build/task is run, Eg, 'windows' and 'linux'. When it's used in build commands, it also can be specified in 'os/arch/variant' format for the resulting image. Eg, linux/arm/v7. The 'arch' and 'variant' parts are optional.

--pull-request-trigger-enabled

Indicates whether the source control pull request trigger is enabled. The trigger is disabled by default.

accepted values: false, true
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--schedule

Schedule for a timer trigger represented as a cron expression. An optional trigger name can be specified using --schedule name:schedule format. Multiples supported by passing --schedule multiple times.

--secret-arg

Secret build argument in '--secret-arg name[=value]' format. Multiples supported by passing --secret-arg multiple times.

--set

Task value in '--set name[=value]' format. Multiples supported by passing --set multiple times.

--set-secret

Secret task value in '--set-secret name[=value]' format. Multiples supported by passing --set-secret multiple times.

--source-trigger-name

The name of the source trigger.

default value: defaultSourceTriggerName
--status

The current status of task.

accepted values: Disabled, Enabled
default value: Enabled
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--target

The name of the target build stage.

--timeout

The timeout in seconds.

default value: 3600
--update-trigger-endpoint

The full URL of the endpoint to receive base image update trigger notifications.

--update-trigger-payload-type

Indicates whether to include metadata about the base image trigger in the payload alongwith the update trigger token, when a notification is sent.

accepted values: Default, Token
default value: Default
--values

The task values/parameters file path relative to the source context.

az acr task delete

Delete a task from an Azure Container Registry.

az acr task delete --name
                   --registry
                   [--resource-group]
                   [--subscription]
                   [--yes]

Examples

Delete a task from an Azure Container Registry.

az acr task delete -n MyTask -r MyRegistry

Required Parameters

--name -n

The name of the task.

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--yes -y

Do not prompt for confirmation.

az acr task list

List the tasks for an Azure Container Registry.

az acr task list --registry
                 [--query-examples]
                 [--resource-group]
                 [--subscription]

Examples

List tasks and show the results in a table.

az acr task list -r MyRegistry -o table

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az acr task list-runs

List all of the executed runs for an Azure Container Registry, with the ability to filter by a specific Task.

az acr task list-runs --registry
                      [--image]
                      [--name]
                      [--resource-group]
                      [--run-status {Canceled, Error, Failed, Queued, Running, Started, Succeeded, Timeout}]
                      [--subscription]
                      [--top]

Examples

List all of the runs for a registry and show the results in a table.

az acr task list-runs -r MyRegistry -o table

List runs for a task and show the results in a table.

az acr task list-runs -r MyRegistry -n MyTask -o table

List the last 10 successful runs for a registry and show the results in a table.

az acr task list-runs -r MyRegistry --run-status Succeeded --top 10 -o table

List all of the runs that built the image 'hello-world' for a registry and show the results in a table.

az acr task list-runs -r MyRegistry --image hello-world -o table

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--image -t

The name of the image. May include a tag in the format 'name:tag' or digest in the format 'name@digest'.

--name -n

The name of the task.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--run-status

The current status of run.

accepted values: Canceled, Error, Failed, Queued, Running, Started, Succeeded, Timeout
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--top

Limit the number of latest runs in the results.

default value: 15

az acr task logs

Show logs for a particular run. If no run-id is supplied, show logs for the last created run.

az acr task logs --registry
                 [--image]
                 [--name]
                 [--resource-group]
                 [--run-id]
                 [--subscription]

Examples

Show logs for the last created run in the registry.

az acr task logs -r MyRegistry

Show logs for the last created run in the registry, filtered by task.

az acr task logs -r MyRegistry -n MyTask

Show logs for a particular run.

az acr task logs -r MyRegistry --run-id runId

Show logs for the last created run in the registry that built the image 'hello-world'.

az acr task logs -r MyRegistry --image hello-world

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--image -t

The name of the image. May include a tag in the format 'name:tag' or digest in the format 'name@digest'.

--name -n

The name of the task.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--run-id

The unique run identifier.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az acr task run

Manually trigger a task that might otherwise be waiting for git commits or base image update triggers.

az acr task run --name
                --registry
                [--agent-pool]
                [--arg]
                [--context]
                [--file]
                [--no-logs]
                [--no-wait]
                [--resource-group]
                [--secret-arg]
                [--set]
                [--set-secret]
                [--subscription]
                [--target]
                [--update-trigger-token]

Examples

Trigger a task run.

az acr task run -n MyTask -r MyRegistry

Trigger a task run by overriding the context and file passed during Task create with a remote repository.

az acr task run -n MyTask -r MyRegistry -c https://github.com/Azure-Samples/acr-build-helloworld-node.git -f Dockerfile

Trigger a task run by overriding the context and file passed during Task create with a local context.

az acr task run -n MyTask -r MyRegistry -c . -f Dockerfile

Trigger a task run by adding or overriding build arguments set during Task create.

az acr task run -n MyTask -r MyRegistry --arg DOCKER_CLI_BASE_IMAGE=docker:18.03.0-ce-git

Required Parameters

--name -n

The name of the task.

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--agent-pool

The name of the agent pool.

--arg

Build argument in '--arg name[=value]' format. Multiples supported by passing '--arg` multiple times.

--context -c

The full URL to the source code repository (Requires '.git' suffix for a github repo) or the repository of an OCI artifact in an Azure container registry (e.g., 'oci://myregistry.azurecr.io/myartifact:mytag'). If '/dev/null' is specified, the value will be set to None and ignored.

--file -f

Relative path of the the task/docker file to the source code root folder. Task files must be suffixed with '.yaml' or piped from the standard input using '-'.

--no-logs

Do not show logs after successfully queuing the build.

--no-wait

Do not wait for the run to complete and return immediately after queuing the run.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--secret-arg

Secret build argument in '--secret-arg name[=value]' format. Multiples supported by passing --secret-arg multiple times.

--set

Task value in '--set name[=value]' format. Multiples supported by passing --set multiple times.

--set-secret

Secret task value in '--set-secret name[=value]' format. Multiples supported by passing --set-secret multiple times.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--target

The name of the target build stage.

--update-trigger-token

The payload that will be passed back alongwith the base image trigger notification.

az acr task show

Get the properties of a named task for an Azure Container Registry.

az acr task show --name
                 --registry
                 [--query-examples]
                 [--resource-group]
                 [--subscription]
                 [--with-secure-properties]

Examples

Get the properties of a task, displaying the results in a table.

az acr task show -n MyTask -r MyRegistry -o table

Get the properties of a task, including secure properties.

az acr task show -n MyTask -r MyRegistry --with-secure-properties

Required Parameters

--name -n

The name of the task.

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--with-secure-properties

Indicates whether the secure properties of a task should be returned.

az acr task show-run

Get the properties of a specified run of an Azure Container Registry Task.

az acr task show-run --registry
                     --run-id
                     [--resource-group]
                     [--subscription]

Examples

Get the details of a run, displaying the results in a table.

az acr task show-run -r MyRegistry --run-id runId -o table

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

--run-id

The unique run identifier.

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az acr task update

Update a task for an Azure Container Registry.

az acr task update --name
                   --registry
                   [--agent-pool]
                   [--arg]
                   [--auth-mode {Default, None}]
                   [--base-image-trigger-enabled {false, true}]
                   [--base-image-trigger-type {All, Runtime}]
                   [--commit-trigger-enabled {false, true}]
                   [--context]
                   [--cpu]
                   [--file]
                   [--git-access-token]
                   [--image]
                   [--no-cache {false, true}]
                   [--no-push {false, true}]
                   [--platform]
                   [--pull-request-trigger-enabled {false, true}]
                   [--resource-group]
                   [--secret-arg]
                   [--set]
                   [--set-secret]
                   [--status {Disabled, Enabled}]
                   [--subscription]
                   [--target]
                   [--timeout]
                   [--update-trigger-endpoint]
                   [--update-trigger-payload-type {Default, Token}]
                   [--values]

Examples

Update base image updates to trigger on all dependent images of a multi-stage dockerfile, and status of a task in an Azure Container Registry.

az acr task update -n MyTask -r MyRegistry --base-image-trigger-type All --status Disabled

Update platform for the Build step of your Task to Windows (prev Linux).

az acr task update -n MyTask -r MyRegistry --platform Windows

Update task's triggers and context for an Azure Container Registry.

az acr task update -n hello-world -r MyRegistry -f Dockerfile \
    --commit-trigger-enabled false --pull-request-trigger-enabled true \
    -c https://msazure.visualstudio.com/DefaultCollection/Project/_git/Repo#Branch:Folder

Update a task for an Azure Container Registry. (autogenerated)

az acr task update --image MyImage --name MyTask --registry MyRegistry \
    --context https://github.com/Azure-Samples/acr-build-helloworld-node.git

Required Parameters

--name -n

The name of the task.

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

Optional Parameters

--agent-pool

The name of the agent pool.

--arg

Build argument in '--arg name[=value]' format. Multiples supported by passing '--arg` multiple times.

--auth-mode

Auth mode of the source registry.

accepted values: Default, None
--base-image-trigger-enabled

Indicates whether the base image trigger is enabled.

accepted values: false, true
--base-image-trigger-type

The type of the auto trigger for base image dependency updates.

accepted values: All, Runtime
--commit-trigger-enabled

Indicates whether the source control commit trigger is enabled.

accepted values: false, true
--context -c

The full URL to the source code repository (Requires '.git' suffix for a github repo) or the repository of an OCI artifact in an Azure container registry (e.g., 'oci://myregistry.azurecr.io/myartifact:mytag'). If '/dev/null' is specified, the value will be set to None and ignored.

--cpu

The CPU configuration in terms of number of cores required for the run.

--file -f

Relative path of the the task/docker file to the source code root folder. Task files must be suffixed with '.yaml' or piped from the standard input using '-'.

--git-access-token

The access token used to access the source control provider.

--image -t

The name and tag of the image using the format: '-t repo/image:tag'. Multiple tags are supported by passing -t multiple times.

--no-cache

Indicates whether the image cache is enabled.

accepted values: false, true
--no-push

Indicates whether the image built should be pushed to the registry.

accepted values: false, true
--platform

The platform where build/task is run, Eg, 'windows' and 'linux'. When it's used in build commands, it also can be specified in 'os/arch/variant' format for the resulting image. Eg, linux/arm/v7. The 'arch' and 'variant' parts are optional.

--pull-request-trigger-enabled

Indicates whether the source control pull request trigger is enabled. The trigger is disabled by default.

accepted values: false, true
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--secret-arg

Secret build argument in '--secret-arg name[=value]' format. Multiples supported by passing --secret-arg multiple times.

--set

Task value in '--set name[=value]' format. Multiples supported by passing --set multiple times.

--set-secret

Secret task value in '--set-secret name[=value]' format. Multiples supported by passing --set-secret multiple times.

--status

The current status of task.

accepted values: Disabled, Enabled
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--target

The name of the target build stage.

--timeout

The timeout in seconds.

--update-trigger-endpoint

The full URL of the endpoint to receive base image update trigger notifications.

--update-trigger-payload-type

Indicates whether to include metadata about the base image trigger in the payload alongwith the update trigger token, when a notification is sent.

accepted values: Default, Token
--values

The task values/parameters file path relative to the source context.

az acr task update-run

Patch the run properties of an Azure Container Registry Task.

az acr task update-run --registry
                       --run-id
                       [--no-archive {false, true}]
                       [--resource-group]
                       [--subscription]

Examples

Update an existing run to be archived.

az acr task update-run -r MyRegistry --run-id runId --no-archive false

Required Parameters

--registry -r

The name of the container registry. You can configure the default registry name using az configure --defaults acr=<registry name>.

--run-id

The unique run identifier.

Optional Parameters

--no-archive

Indicates whether the run should be archived.

accepted values: false, true
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.