Docker@2 - Docker v2 task

Build or push Docker images, log in or log out, start or stop containers, or run a Docker command.

Syntax

# Docker v2
# Build or push Docker images, login or logout, start or stop containers, or run a Docker command.
- task: Docker@2
  inputs:
  # Container Repository
    #containerRegistry: # string. Container registry. 
    #repository: # string. Optional. Use when command != login && command != logout && command != start && command != stop. Container repository. 
  # Commands
    command: 'buildAndPush' # 'buildAndPush' | 'build' | 'push' | 'login' | 'logout' | 'start' | 'stop'. Required. Command. Default: buildAndPush.
    Dockerfile: '**/Dockerfile' # string. Required when command = build || command = buildAndPush. Dockerfile. Default: **/Dockerfile.
    #buildContext: '**' # string. Optional. Use when command = build || command = buildAndPush. Build context. Default: **.
    #tags: '$(Build.BuildId)' # string. Optional. Use when command = build || command = push || command = buildAndPush. Tags. Default: $(Build.BuildId).
    #arguments: # string. Optional. Use when command != login && command != logout && command != buildAndPush. Arguments. 
    #addPipelineData: true # boolean. Add Pipeline metadata to image(s). Default: true.
    #addBaseImageData: true # boolean. Add base image metadata to image(s). Default: true.
    #container: # string. Optional. Use when command = start || command = stop. Container.

Inputs

containerRegistry - Container registry
string.

Name of the Docker registry service connection. Required for commands that perform authentication with a registry.

repository - Container repository
string. Optional. Use when command != login && command != logout && command != start && command != stop.

Specifies the name of the repository.

command - Command
string. Required. Allowed values: buildAndPush, build, push, login, logout, start, stop. Default value: buildAndPush.

Specifies the Docker command to run.

Dockerfile - Dockerfile
string. Required when command = build || command = buildAndPush. Default value: **/Dockerfile.

Specifies the path to the Docker file. The task uses the first Docker file it finds to build the image.

buildContext - Build context
string. Optional. Use when command = build || command = buildAndPush. Default value: **.

Specifies the path to the build context. Pass ** to indicate the directory that contains the Docker file.

tags - Tags
string. Optional. Use when command = build || command = push || command = buildAndPush. Default value: $(Build.BuildId).

Specifies a list of comma-separated tags. These tags are used in build, push and buildAndPush commands.

arguments - Arguments
string. Optional. Use when command != login && command != logout && command != buildAndPush.

Specifies additional arguments to pass to the Docker client. If using the value buildAndPush for the command parameter, the arguments property is ignored.

Example: Using the build command, --build-arg HTTP_PROXY=http://10.20.30.2:1234 --quiet.

addPipelineData - Add Pipeline metadata to image(s)
boolean. Default value: true.

By default, pipeline data like source branch name, or build ID are added and help 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.

addBaseImageData - Add base image metadata to image(s)
boolean. Default value: true.

By default, base image data like base image name, or digest are added and help with traceability. You can opt out of this default behavior.

container - Container
string. Optional. Use when command = start || command = stop.

Specifies the name of the container resource to start or stop. Use this command with start and stop commands.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.

DockerOutput
Specifies the path to the files that contain the command output. You can list two file paths on separate lines for the buildAndPush command, and one file path for any other command.

Remarks

The following are the key benefits of using the Docker task instead of directly using Docker client binary in a 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 signed in, you can add follow up tasks that execute other tasks or scripts by leveraging the sign on used by the Docker task. For example, use the Docker task to sign in to any Azure Container Registry, and then use another task or script to build and push an image to the registry.

• Metadata added as labels - The task adds traceability-related metadata to the image in 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

Troubleshooting

Why does the Docker task ignore arguments passed to the buildAndPush command?

A Docker task configured using the buildAndPush command ignores the arguments passed because they become ambiguous to the internal build and push commands. You can split your command into separate build and push steps and pass the suitable arguments. For example, see this stackoverflow post.

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

Examples

Login

YAML

The following YAML snippet shows a container registry sign on using a Docker registry service connection.

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

Classic

Use a Docker registry connection with the Docker login command. Set the Container Repository to your Docker registry service connection.

Build and Push

A convenience command called buildAndPush allows the build and push of images to a container registry in a single command.

YAML

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 you want to build and push to a specific authenticated container registry instead of building and pushing to all authenticated container registries at once, explicitly specify the containerRegistry input with command: buildAndPush as shown:

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

Classic

Use the buildAndPush command to build and push images to a container registry in a single command. See the example for building and pushing multiple tags of an image with authentication to DockerHub.

You can build and push without authentication. In the buildAndPush tasks, the images for tag1 and tag2 are built and pushed to the container registries corresponding to service connections set up in the previous two log on tasks.

Logout

YAML

The following YAML snippet shows how to log out from a container registry using a Docker registry service connection.

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

Classic

Log out from your Docker registry service connection with the Docker task.

Start/stop

Use this task to control job and service containers. This usage is uncommon, but occasionally used in 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 are used to pass additional arguments for build or push commands using Docker client binary as shown in the example.

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. buildAndPush is a convenience command (build followed by push), arguments input is ignored when it is used.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	2.172.0 or greater
Task category	Build