Edit

Share via

Use Azure Pipelines to build and push container images to registries

  • Article

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

This article guides you through the setup and configuration in Azure Pipelines to build and push a Docker image to an Azure Container Registry and Docker Hub. Additionally, it details the use of the System.AccessToken for secure authentication within your pipeline.

This article guides you through the setup and configuration for using Azure Pipelines to build and push a Docker image to a Docker Hub. Additionally, it details the use of the System.AccessToken for secure authentication within your pipeline.

You learn how to create a YAML pipeline to build and push a Docker image to a container registry using he Docker@2 task.

Prerequisites

Product Requirements
Azure DevOps - An Azure DevOps project.
- Permissions:
    - To grant access to all pipelines in the project: You must be a member of the Project Administrators group.
    - To create service connections: You must have the Administrator or Creator role for service connections.
- If you're using a self-hosted agent, ensure Docker is installed and the Docker engine is running with elevated privileges. Microsoft-hosted agents have Docker preinstalled.
GitHub - A GitHub account.
- A GitHub repository with a Dockerfile. Use the sample repository if you don't have your own project.
- A GitHub service connection to authorize Azure Pipelines.
Azure - An Azure subscription.
- An Azure Container Registry.
Docker Hub - A Docker Hub account.
- A Docker Hub image repository.
  • Project requirements: An Azure DevOps project.
  • Permissions:
  • Subscriptions:
    • A GitHub account. If you don't have one, you can create one for free at GitHub.
    • Docker Hub account: You need a Docker Hub account. If you don't have one, you can create one for free at Docker Hub.
  • Repository: A GitHub repository with a Dockerfile. If you don't have one, you can use the sample repository
  • Service connection: A GitHub Enterprise Server service connection. If you don't have one, you can create one in your Azure DevOps project settings. For more information to create a service connection, see Service connections.
  • Container registry: A (Docker Hub container registry
  • Software requirements: Docker must be is installed and the Docker engine running with elevated privileges on your self-hosted agent.

Create a Docker service connection

Before pushing container images to a registry, you need to create a service connection in Azure DevOps. This service connection stores the credentials required to securely authenticate with the container registry. Go to Service connections in your Azure DevOps project settings to create a new Docker Registry service connection.

Choose the Docker Hub option under Docker registry service connection and provide your username and password to create a Docker service connection.

Create a YAML pipeline to build and push a Docker image

The Docker@2 task is designed to streamline the process of building, pushing, and managing Docker images within your Azure Pipelines. This task supports a wide range of Docker commands, including build, push, login, logout, start, stop, and run.

Use following steps to create a YAML pipeline that uses the Docker@2 task to build and push the image.

  1. Go to your Azure DevOps project and select Pipelines from the left-hand menu.

  2. Select New pipeline.

  3. Select the location of your source repository.

  4. Select GitHub as the location of your source code and select your repository.

    • If you're redirected to GitHub to sign in, enter your GitHub credentials.
    • If you're redirected to GitHub to install the Azure Pipelines app, select Approve and install.

  5. Select the Starter pipeline template to create a basic pipeline configuration.

  6. Replace the contents of azure-pipelines.yml with the following code:

    
 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest' 

 variables:
   repositoryName: '<target repository name>'

 steps:
 - task: Docker@2
   inputs:
     containerRegistry: '<docker connection>'
     repository: $(repositoryName)
     command: 'buildAndPush'
     Dockerfile: '**/Dockerfile'

  7. Edit the pipeline YAML file as follows:

    • Based on whether you're deploying a Linux or Windows app, make sure to respectively set vmImage to either ubuntu-latest or windows-latest.

      If you're using a self-hosted agent, set vmImage to the name of the pool that contains the self-hosted agent with Docker capability. You can add the demands: property to ensure an agent with Docker installed is selected. For example:

          pool:
      name: <your agent pool>
      demands: docker

    • Replace <docker connection> with the name of the Docker service connection you created earlier.

    • Replace <target repository name> with the name of the repository in the container registry where you want to push the image. For example, <your-docker-hub-username>/<repository-name>.

  8. When you're done, select Save and run.

  9. When you save the azure-pipelines.yml file to your repository, you're prompted to add a commit message. Enter a message, and then select Save and run.

When using self-hosted agents, be sure that Docker is installed on the agent's host, and the Docker engine/daemon is running with elevated privileges.

To build the image, Docker must be installed on the agent's host and the Docker engine/daemon must be running with elevated privileges.

Use the following steps to create your pipeline using the YAML pipeline editor.

  1. Go to your collection and create a project.

  2. In your project, select Pipelines.

  3. Select Create Pipeline.

  4. Select GitHub Enterprise Server as the location for your source code.

  5. If you haven't already, authorize Azure Pipelines to connect to your GitHub Enterprise Server account.

    1. Select Connect to GitHub Enterprise Server.
    2. Enter your account details, and then select Verify and save.

  6. Select your repository. If you're redirected to GitHub to install the Azure Pipelines app, select Approve and install.

  7. To configure your pipeline, select the Build a Docker image template.

  8. In the YAML pipeline editor, replace the contents of the YAML file with the following code:

    
trigger:
- main

pool:
  name: default
  demands: docker

variables:
  repositoryName: '<target repository name>'

steps:
- task: Docker@2
  inputs:
    containerRegistry: '<docker connection>'
    repository: $(repositoryName)
    command: 'buildAndPush'
    Dockerfile: '**/Dockerfile'

  9. Edit the pipeline YAML file as follows:

    • Replace the pool name with the name of the pool that contains your self-hosted agent with Docker capability.
    • Replace <target repository name> with the name of the repository in the container registry where you want to push the image. For example, <your-docker-hub-username>/<repository-name>.
    • Replace <docker connection> with the name of the Docker service connection you created earlier.

  10. Select Save and run.

  11. On the Save and run page, select Save and run again.

You can watch the pipeline run and view the logs to see the Docker image being built and pushed to the container registry.

Using System.AccessToken for Authentication in Docker@2 Task

You can authenticate with a container registry using the System.AccessToken provided by Azure DevOps. This token allows secure access to resources within your pipeline without exposing sensitive credentials.

The following YAML pipeline example, the Docker@2 task is used to sign in to the container registry and push the Docker image. The System.AccessToken is set as an environment variable to authenticate the Docker commands.

Replace <docker connection> with your Docker registry service connection name. Replace <your repository> with the name of your Docker repository.

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

variables:
  SYSTEM_ACCESSTOKEN: $(System.AccessToken)

steps:
- task: Docker@2
  inputs:
    command: login
    containerRegistry: '<docker connection>'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

- task: Docker@2
  inputs:
    command: buildAndPush
    repository: '<your repository>'
    dockerfile: '**/Dockerfile'
    tags: |
      $(Build.BuildId)
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)