Use Azure Pipelines to build and push container images to registries

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

This article guides you through the setup and configuration for using Azure Pipelines to build and push a Docker image to an Azure Container Registry, Docker Hub, and Google Artifact Registry. 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. The Docker@2 task is used to build and push the image to the container registry.

Prerequisites

• An Azure DevOps project.
• A container registry (Docker Hub, Google Artifact Registry, or Azure Container Registry).
• A GitHub repository with a Dockerfile. If you don't have one, you can use the sample repository In your browser, go the sample repository then fork it to your GitHub account.
• Docker. If using a self-hosted agent, ensure Docker is installed and the Docker engine running with elevated privileges. Microsoft-hosted agents have Docker preinstalled.

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 the Service connections page in your Azure DevOps project to create a new service connection and select the Docker Registry connection type.

There are different processes to create a service connection for a Docker Hub and a Google Artifact Registry.

Docker Hub

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

Azure Container Registry

Choose the Azure Container Registry option under Docker registry service connection and provide the information required by the authentication method you choose.

You can also create your pipeline using the Docker template to build and push an image to Azure Container Registry. This template automatically creates a service connection and a YAML pipeline for you. For more information, see Use Docker YAML to build and push images to Azure Container Registry.

Google Artifact Registry

To create a Docker service connection associated with Google Artifact Registry:

1. Open your project in the Google Cloud Platform (GCP) Console and then open Cloud Shell

2. To save time typing your project ID and Compute Engine zone options, set default configuration values by running the following commands:

   gcloud config set project [PROJECT_NAME]
   gcloud config set compute/zone [ZONE]
   

3. Replace [PROJECT_NAME] with the name of your GCP project and replace [ZONE] with the name of the zone that you're going to use for creating resources. If you're unsure about which zone to pick, use us-central1-a. For example:

   gcloud config set project azure-pipelines-test-project-12345
   gcloud config set compute/zone us-central1-a
   

4. Enable the Artifact Registry API for your project:

   gcloud services enable artifactregistry.googleapis.com
   gcloud services enable containerregistry.googleapis.com
   

5. Create a service account for Azure Pipelines to publish Docker images:

   gcloud iam service-accounts create azure-pipelines-publisher --display-name "Azure Pipelines Publisher"
   

6. Assign the Storage Admin identity and access management (IAM) role to the service account:

   PROJECT_NUMBER=$(gcloud projects describe \
   $(gcloud config get-value core/project) \
   --format='value(projectNumber)')
   
   AZURE_PIPELINES_PUBLISHER=$(gcloud iam service-accounts list \
       --filter="displayName:Azure Pipelines Publisher" \
       --format='value(email)')
   
   gcloud projects add-iam-policy-binding \
       $(gcloud config get-value core/project) \
       --member serviceAccount:$AZURE_PIPELINES_PUBLISHER \
       --role roles/storage.admin
   

7. Generate a service account key:

   gcloud iam service-accounts keys create \
   azure-pipelines-publisher.json --iam-account $AZURE_PIPELINES_PUBLISHER
   
   tr -d '\n' < azure-pipelines-publisher.json > azure-pipelines-publisher-oneline.json
   

   Launch Code Editor by clicking the button in the upper-right corner of Cloud Shell:

   

8. Open the file named azure-pipelines-publisher-oneline.json. You need the content of this file in one of the following steps:

9. In your Azure DevOps organization, select Project settings and then select Pipelines -> Service connections.

10. Select New service connection and choose Docker Registry

11. In the dialog, enter values for the following fields:

    • Docker Registry: https://gcr.io/[PROJECT-ID], where [PROJECT-ID] is the name of your GCP project.
    • Docker ID: _json_key
    • Docker Password: Paste the contents of azure-pipelines-publisher-oneline.json
    • Service connection name: gcrServiceConnection

12. Select Save to create the service connection

Create an Azure Pipeline to build and push a Docker image

Docker Hub

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.

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

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

2. Select New pipeline to create a new pipeline.

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

4. 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.

5. Select your repository. If you're redirected to GitHub

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

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

8. 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: docker property to ensure an agent with Docker installed is selected.

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

10. 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>.

    
     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'
    
    

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

12. 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.

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

Azure Container Registry

You can create a YAML pipeline to build and push a Docker image to an Azure container registry using the Docker template as described in Use Docker YAML to build and push Docker images to Azure Container Registry or use the following steps.

The Docker@2 task is used to build and push the image to the container registry. 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.

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

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

2. Select New pipeline to create a new pipeline.

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

4. 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.

5. Select your repository.

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

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

8. 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: docker property to ensure an agent with Docker installed is selected.

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

10. Replace <target repository name> with the name of the repository in the container registry where you want to push the image. For example, myregistry.azurecr.io/myimage.

    
    trigger:
    - main
    
    pool:
    vmImage: 'ubuntu-latest' 
    
    variables:
    repositoryName: '<target repository name>' 
    
    steps:
    - task: Docker@2
    inputs:
    containerRegistry: '<azure resource manager connection>'
    repository: $(repositoryName)
    command: 'buildAndPush'
    Dockerfile: '**/Dockerfile'
    
    

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

12. 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.

Google Artifact Registry

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.

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

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

2. Select New pipeline to create a new pipeline.

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

4. 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.

5. Select your repository.

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

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

8. 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: docker property to ensure an agent with Docker installed is selected.

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

10. Replace <target repository name> with the name of the repository in the container registry where you want to push the image. For example, <your-project-id>/<your-image-name>.

    
    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'
    
    

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

12. 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.

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)

Related articles

• Use Docker YAML to build and push images to Azure Container Registry
• Use Docker YAML to build and push images to Azure Container Registry (self-hosted agent)