Docker task

Azure Pipelines | Azure DevOps Server 2019 | TFS 2018

Use this task in a build or release pipeline to build, tag, push, or run Docker images, or to run a Docker command.

The built-in Docker task enables you to build Docker images, push Docker images to an authenticated Docker registry, run Docker images, or execute other operations offered by the Docker CLI:

  • Use Docker best practices: Usage of pre-defined build variables with Docker task allows for building and pushing an image tagged with $(Build.BuildId). The task also adds rich metadata about the source repository, commit, and build information to the image as labels.
  • Conform to Docker standards: The task takes care of qualifying the image name with the registry hostname and port image. It helps conform to Docker naming conventions by performing minor fixes such as converting upper case characters to lower case and removing spaces in image names that could occur as a result of using $(Build.Repository.Name) for naming images.
  • Manage secrets: The task makes it easy to use either a Docker registry service connection for connecting to any private container registry or an Azure Service Connection for connecting to ACR. For example, in the case of ACR, you don't need to enable admin user and manage the username and password as secrets. The task will use the Azure Service Connection to sign into ACR. After you have used the Docker task to sign in, the session is maintained for the duration of the job, allowing you to use follow-up tasks to execute any scripts by leveraging the login by the Docker task. For example, you can use the Docker task to sign into ACR and then use a subsequent script to pull an image and scan the container image for vulnerabilities.

See also Docker Installer task and Content Trust for build and push.

Login command

Azure Container Registry

ParametersDescription
command
Command
(Required) Use the value login when running the task.
Default value: build
containerregistrytype
Container registry type
(Optional) Azure Container Registry if using ACR or Container Registry if using any other container registry.
Default value: Azure Container Registry
azureSubscriptionEndpoint
Azure subscription
(Required) Name of the Azure Service Connection. See Azure Resource Manager service connection to manually set up the connection.
azureContainerRegistry
Azure container registry
(Required) Name of the Azure Container Registry.

This YAML example demonstrates logging into Azure Container Registry:

variables:
    azureSubscriptionEndpoint: Contoso
    azureContainerRegistry: contoso.azurecr.io
steps:
- task: Docker@1
  displayName: Container registry login
  inputs:
    command: login
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)

Other container registries

The containerregistrytype input is required when using any container registry other than ACR. Use containerregistrytype: Container Registry in this case.

ParametersDescription
command
Command
(Required) Use the value login when running the task.
Default value: build
containerregistrytype
Container registry type
(Required) Azure Container Registry if using ACR or Container Registry if using any other container registry.
Default value: Azure Container Registry
dockerRegistryEndpoint
Docker registry service connection
(Required) Docker registry service connection.

This YAML example demonstrates logging into a container registry other than ACR. Contoso is the name of the Docker registry service connection:

- task: Docker@1
  displayName: Container registry login
  inputs:
    command: login
    containerregistrytype: Container Registry
    dockerRegistryEndpoint: Contoso

Build command

ParametersDescription
command
Command
(Optional) Use the value build when running the task.
Default value: build
dockerFile
Dockerfile
(Required) Path to the Docker file.
imageName
Image name
(Required) Name of the docker image to be built.
Default value: $(Build.Repository.Name):$(Build.BuildId)
qualifyImageName
Qualify image name
(Optional) Qualify the image name with the Docker registry connection's hostname if not otherwise specified.
Default value: true
useDefaultContext
Use default build context
(Optional) Accepts boolean values. If true, sets the build context to the directory containing Dockerfile.
Default value: true
buildContext
Build context
(Required if useDefaultContext == false) Path to the buildContext.
includeSourceTags
Include source tags
(Optional) Include Git tags when building the image.
Default value: false
includeLatestTag
Include latest tag
(Optional) Include the latest tag when building the Docker image.
Default value: false
addDefaultLabels
Add default labels
(Optional) Add metadata such as repository, commit, and build information to the container image by using Docker labels.
Default value: true
arguments
Arguments
(Optional) Additional arguments to be passed to the Docker CLI.

This YAML example builds an image with the image name qualified using the container registry hostname as specified in the inputs associated with Azure Container Registry: builds an image with the image name qualified using the container registry hostname as specified in the inputs associated with Azure Container Registry:

- task: Docker@1
  displayName: Build image
  inputs:
    command: build
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)
    dockerFile: Dockerfile
    imageName: $(Build.Repository.Name)

Tag command

ParametersDescription
command
Command
(Required) Use the value tag when running the task.
Default value: build
tagMultipleImages
Tag multiple images
(Optional) Tag multiple images by using a text file that contains the names of the Docker images to tag.
Default value: false
imageName
Image name
(Required if tagMultipleImages == false or if tagMultipleImages is not specified) Name of the docker image to be tagged.
Default value: $(Build.Repository.Name):$(Build.BuildId)
arguments
Arguments
(Optional) Tags that must be applied to the image.
imageNamesPath
Image names path
(Required only if tagMultipleImages == true) Points to a text file where each image name is contained on its own line. For example:
  • Imagename1:tag1
  • Imagename2:tag2
  • Imagename3
If only the image name is provided, that image will be tagged as latest.
qualifyImageName
Qualify image name
(Optional) Qualify the image name with the Docker registry service connection's hostname if not otherwise specified.
Default value: true
includeSourceTags
Include source tags
(Optional) Include Git tags when tagging the image.
Default value: false

This YAML example tags the image:

- task: Docker@1
  displayName: Tag image
  inputs:
    command: tag
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)
    imageName: $(azureContainerRegistry)/$(Build.Repository.Name):latest
    arguments: $(azureContainerRegistry)/$(Build.Repository.Name):$(Build.BuildId)

Push command

ParametersDescription
command
Command
(Required) Use the value push when running the task.
Default value: build
pushMultipleImages
Push multiple images
(Optional) Push multiple images by using a text file that contains the names of the Docker images to push.
Default value: false
imageName
Image name
(Required if pushMultipleImages == false or if pushMultipleImages is not specified) Name of the docker image to be pushed.
Default value: $(Build.Repository.Name):$(Build.BuildId)
imageNamesPath
Image names path
(Required only if pushMultipleImages == true) Points to a text file where each image name is contained on its own line. For example:
  • Imagename1:tag1
  • Imagename2:tag2
  • Imagename3
If only the image name is provided, all tags of the image will be pushed.
qualifyImageName
Qualify image name
(Optional) Qualify the image name with the Docker registry service connection's hostname if not otherwise specified.
Default value: true
arguments
Arguments
(Optional) Additional arguments to be passed to the Docker CLI.
includeSourceTags
Include source tags
(Optional) Include Git tags when pushing the image.
Default value: false
imageDigestFile
Image digest file
(Optional) Path to a file that is created and populated with the full image repository digest of the Docker image that was pushed.

This YAML example pushes an image to a container registry:

- task: Docker@1
  displayName: Push image
  inputs:
    command: push
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)
    imageName: $(Build.Repository.Name):$(Build.BuildId)

Run command

ParametersDescription
command
Command
(Required) Use the value run when running the task.
Default value: build
imageName
Image name
(Required) Name of the docker image to run.
Default value: $(Build.Repository.Name):$(Build.BuildId)
qualifyImageName
Qualify image name
(Optional) Qualify the image name with the Docker registry service connection's hostname if not otherwise specified.
Default value: true
containerName
Container name
(Optional) Name of the Docker container to run.
ports
Ports
(Optional) Ports in the Docker container to publish to the host. Specify each host-port:container-port binding on a new line.
volumes
Volumes
(Optional) Volumes to mount from the host. Specify each host-dir:container-dir on a new line.
envVars
Environment variables
(Optional) Environment variables for the Docker container. Specify each name-value pair on a new line.
workingDirectory
Working directory
(Optional) Working directory for the Docker container.
entrypointOverride
Entry point override
(Optional) Overrides the default entry point for the Docker container.
containerCommand
Container command
(Optional) The Docker run command first creates a writeable container layer over the specified image, and then starts it by using the specified run command. For example, if the image contains a simple Python Flask web application you can specify python app.py to launch the web application.
runInBackground
Run in background
(Optional) Runs the Docker container in the background. Accepts Boolean values.
Default value: true
restartPolicy
Restart policy
(Required only when runInBackground == true) Acceptable values are no, onFailure, always, and unlessStopped.
Default value: no
maxRestartRetries
Maximum restart retries
(Required only when runInBackground == true and restartPolicy == onFailure) The maximum number of restart retries attempted by the Docker daemon.

This YAML example executes the run command:

- task: Docker@1
  displayName: Run image
  inputs:
    command: run
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)
    imageName: $(Build.Repository.Name):$(Build.BuildId)

Logout command

ParametersDescription
command
Command
(Required) Use the value logout when running the task.
Default value: build

This YAML example logs out of a container registry:

- task: Docker@1
  displayName: Container registry logout
  inputs:
    command: logout
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureContainerRegistry: $(azureContainerRegistry)

Advanced Options

ParametersDescription
dockerHostEndpoint
Docker host service connection
(Optional) Select a Docker host connection. Defaults to the agent's host.
enforceDocker
NamingConvention

Force the image name to follow Docker naming conventions.
(Optional) If enabled, the Docker image name will be modified to follow Docker naming conventions. Converts upper case characters to lower case and removes spaces in the image name.
Default value: true
memoryLimit
Memory limit
(Optional) The maximum amount of memory available to the container as a integer with optional suffixes; for example, 2GB.

Open source

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