Docker task

Article
04/05/2022
4 minutes to read

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

Use this task to build and push Docker images to any container registry using Docker registry service connection.

Overview

Following are the key benefits of using Docker task as compared to directly using docker client binary in script -

Integration with Docker registry service connection - The task makes it easy to use a Docker registry service connection for connecting to any container registry. Once logged in, the user can author follow up tasks to execute any tasks/scripts by leveraging the login already done by the Docker task. For example, you can use the Docker task to sign in to any Azure Container Registry and then use a subsequent task/script to build and push an image to this registry.
Metadata added as labels - The task adds traceability-related metadata to the image in the form of the following labels -
- com.azure.dev.image.build.buildnumber
- com.azure.dev.image.build.builduri
- com.azure.dev.image.build.definitionname
- com.azure.dev.image.build.repository.name
- com.azure.dev.image.build.repository.uri
- com.azure.dev.image.build.sourcebranchname
- com.azure.dev.image.build.sourceversion
- com.azure.dev.image.release.definitionname
- com.azure.dev.image.release.releaseid
- com.azure.dev.image.release.releaseweburl
- com.azure.dev.image.system.teamfoundationcollectionuri
- com.azure.dev.image.system.teamproject

Task Inputs

Parameters	Description
`command` Command	(Required) Possible values: `buildAndPush`, `build`, `push`, `login`, `logout` Added in version 2.173.0: `start`, `stop` Default value: `buildAndPush`
`containerRegistry` Container registry	(Optional) Name of the Docker registry service connection
`repository` Repository	(Optional) Name of repository within the container registry corresponding to the Docker registry service connection specified as input for `containerRegistry`. Prefix with `username/` for DockerHub.
`container` Container	(Required for commands `start` and `stop`) The container resource to start or stop
`tags` Tags	(Optional) Multiline input where each line contains a tag to be used in `build`, `push` or `buildAndPush` commands Default value: `$(Build.BuildId)`
`Dockerfile` Dockerfile	(Optional) Path to the Dockerfile. The task will use the first dockerfile it finds to build the image. Default value: `**/Dockerfile`
`buildContext` Build context	(Optional) Path to the build context Default value: `**`
`arguments` Arguments	(Optional) Additional arguments to be passed onto the docker client Be aware that if you use value `buildAndPush` for the `command` parameter, then the `arguments` property will be ignored.
`addPipelineData` Add Pipeline metadata to image.	(Optional) By default pipeline data like source branch name, build id are added which helps with traceability. For example you can inspect an image to find out which pipeline built the image. You can opt out of this default behavior. Possible values: `true`, `false` Default value: `true`
`addBaseImageData` Add base image metadata to image(s)	(Optional) By default base image data like base image name and digest are added which helps with traceability. You can opt out of this default behavior. Possible values: `true`, `false` Default value: `true`

Following YAML snippet showcases container registry login using a Docker registry service connection -

- task: Docker@2
  displayName: Login to ACR
  inputs:
    command: login
    containerRegistry: dockerRegistryServiceConnection1

Build and Push

A convenience command called buildAndPush allows for build and push of images to container registry in a single command. The following YAML snippet is an example of building and pushing multiple tags of an image to multiple registries -

steps:
- task: Docker@2
  displayName: Login to ACR
  inputs:
    command: login
    containerRegistry: dockerRegistryServiceConnection1
- task: Docker@2
  displayName: Login to Docker Hub
  inputs:
    command: login
    containerRegistry: dockerRegistryServiceConnection2
- task: Docker@2
  displayName: Build and Push
  inputs:
    command: buildAndPush
    repository: contosoRepository # username/contosoRepository for DockerHub
    tags: |
      tag1
      tag2

In the above snippet, the images contosoRepository:tag1 and contosoRepository:tag2 are built and pushed to the container registries corresponding to dockerRegistryServiceConnection1 and dockerRegistryServiceConnection2.

If one wants to build and push to a specific authenticated container registry instead of building and pushing to all authenticated container registries at once, the containerRegistry input can be explicitly specified along with command: buildAndPush as shown below -

steps:
- task: Docker@2
  displayName: Build and Push
  inputs:
    command: buildAndPush
    containerRegistry: dockerRegistryServiceConnection1
    repository: contosoRepository
    tags: |
      tag1
      tag2

Logout

Following YAML snippet showcases container registry logout using a Docker registry service connection -

- task: Docker@2
  displayName: Logout of ACR
  inputs:
    command: logout
    containerRegistry: dockerRegistryServiceConnection1

Start/stop

This task can also be used to control job and service containers. This usage is uncommon, but occasionally used for unique circumstances.

resources:
  containers:
  - container: builder
    image: ubuntu:18.04
steps:
- script: echo "I can run inside the container (it starts by default)"
  target:
    container: builder
- task: Docker@2
  inputs:
    command: stop
    container: builder
# any task beyond this point would not be able to target the builder container
# because it's been stopped

Other commands and arguments

The command and argument inputs can be used to pass additional arguments for build or push commands using docker client binary as shown below -

steps:
- task: Docker@2
  displayName: Login to ACR
  inputs:
    command: login
    containerRegistry: dockerRegistryServiceConnection1
- task: Docker@2
  displayName: Build
  inputs:
    command: build
    repository: contosoRepository # username/contosoRepository for DockerHub
    tags: tag1
    arguments: --secret id=mysecret,src=mysecret.txt

Note

The arguments input is evaluated for all commands except buildAndPush. As buildAndPush is a convenience command (build followed by push), arguments input is ignored for this command.

Troubleshooting

Why does Docker task ignore arguments passed to buildAndPush command?

Docker task configured with buildAndPush command ignores the arguments passed since they become ambiguous to the build and push commands that are run internally. You can split your command into separate build and push steps and pass the suitable arguments. See this stackoverflow post for example.

DockerV2 only supports Docker registry service connection and not support ARM service connection. How can I use an existing Azure service principal (SPN) for authentication in Docker task?

You can create a Docker registry service connection using your Azure SPN credentials. Choose the Others from Registry type and provide the details as follows:

Docker Registry:    Your container registry URL (eg. https://myacr.azurecr.io)
Docker ID:          Service principal client ID
Password:           Service principal key

Open source

This task is open source on GitHub. Feedback and contributions are welcome.