Skip to content

push-image.md

Latest commit

 

History

History
278 lines (189 loc) · 13.9 KB

push-image.md

File metadata and controls

278 lines (189 loc) · 13.9 KB
title Use Azure Pipelines to build and push container images to registries
description Use Azure Pipelines to build and push container images to Docker Hub and Azure Container Registry.
ms.topic tutorial
ms.assetid 3ce59600-a7f8-4a5a-854c-0ced7fdaaa82
ms.author rabououn
ms.date 01/07/2026
monikerRange azure-devops
zone_pivot_groups pipelines-docker-acr

Use Azure Pipelines to build and push container images to registries

[!INCLUDE version-eq-2022]

This article guides you through creating a pipeline to build and push a Docker image to an Azure Container Registry or Docker Hub. By the end of this tutorial, you'll have a working CI/CD pipeline that automatically builds your Docker image and pushes it to your chosen container registry.

Prerequisites

:::zone pivot="acr-registry"

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.

:::zone-end

::: zone pivot="docker-registry"

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.
Docker Hub - A Docker Hub account.
- A Docker Hub image repository.

Create a Docker registry service connection

Before you push container images to a registry, create a service connection in Azure DevOps. This service connection stores the credentials required to securely authenticate with the Azure Container Registry. For more information, see Docker Registry service connections.

  1. In your Azure DevOps project, select Project settings > Service connections.

    :::image type="content" source="../media/project-settings-selection.png" alt-text="Screenshot showing how to navigate to Project settings and Service connections in Azure DevOps.":::

  2. Select New service connection and Docker Registry.

    :::image type="content" source="../media/docker-registry-selection.png" alt-text="Screenshot showing the New service connection menu with Docker Registry option selected.":::

  3. Select Docker Hub and enter the following information:

    Field Description
    Docker ID Enter your Docker ID.
    Docker Password Enter your Docker password.
    Service connection name Enter a name for the service connection.
    Grant access permission to all pipelines Select this option to grant access to all pipelines.

    :::image type="content" source="../media/docker-hub-service-connection-dialog.png" alt-text="Screenshot of the Docker Hub service connection dialog showing fields for Docker ID, password, and service connection name.":::

  4. Select Verify and save.

:::zone-end

Create a pipeline to build and push a Docker image

::: zone pivot="docker-registry"

YAML

The Docker@2 task is used to build and push the image to the container registry. The Docker@2 task streamlines 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 the following steps to create a YAML pipeline that uses the Docker@2 task to build and push the image.

  1. In your Azure DevOps project, select Pipelines and New pipeline.

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

  3. Select your repository.

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

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

    trigger:
- main

pool:
  vmImage: 'ubuntu-latest' 

variables:
  # Replace with the name of your target Docker Hub or Azure Container Registry repository
  repositoryName: '<image-repository-name>' 

steps:
- task: Docker@2
  inputs:
    # Replace with the service connection name created in previous steps
    containerRegistry: '<docker-registry-service-connection-name>'
    repository: $(repositoryName)
    command: 'buildAndPush'
    Dockerfile: '**/Dockerfile'

  6. Edit the pipeline YAML file as follows:

    • Replace <target repository name> with the name of the repository in the container registry where you want to push the image.
    • Replace <docker registry service connection> with the name of the Docker registry service connection you created earlier.

  7. When you're done, select Save and run > Save and run.

  8. Select Job to view the logs and verify the pipeline ran successfully.

Classic

Create a pipeline by using the classic editor

  1. From your Azure DevOps project, select Pipelines and New pipeline

  2. Select Use the classic editor from the Where is your code? page.

  3. On the Select a source page, select GitHub.

  4. Choose your repository and select Continue.

  5. On the Select a template page, select Empty pipeline and Apply.

  6. Select ubuntu latest for the Agent Specification.

    :::image type="content" source="../media/classic-docker-pipeline-dialog.png" alt-text="Screenshot of Azure DevOps classic pipeline editor with ubuntu latest agent specification selected.":::

Add the Docker@2 task to the pipeline

To build and push the image to the container registry, add the Docker@2 task to the pipeline.

  1. Add a task to the Agent job 1.

    :::image type="content" source="../media/classic-pipeline-add-task.png" alt-text="Screenshot of add task icon in the classic pipeline editor.":::

  2. Select the Docker task, and select Add.

  3. Select the buildAndPush task.

  4. For Container Registry, select the service connection you created earlier. If you don't have one, select +New to create a new Docker Hub service connection.

    :::image type="content" source="../media/classic-pipeline-docker-2-build-and-push-task.png" alt-text="Screenshot of Docker@2 task configured to build and push image to Docker Hub, showing container registry and service connection options.":::

Run the pipeline

  1. Select Save and queue > Save and Queue.
  2. On the Run pipeline page, select Save and run.
  3. Select Job to view the logs and verify the pipeline ran successfully.

:::zone-end

::: zone pivot="acr-registry"

YAML

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

  2. Select New pipeline.

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

  4. Select the Docker - Build and push an image to Azure Container Registry template.

  5. Select your Azure subscription and Continue.

  6. Select your container registry, and then select Validate and configure.

    Example YAML pipeline:

    # Docker
# Build and push an image to Azure Container Registry
# https://docs.microsoft.com/azure/devops/pipelines/languages/docker

trigger:
- main

resources:
- repo: self

variables:
  # Container registry service connection established during pipeline creation
  dockerRegistryServiceConnection: '<docker-registry-service-connection-id>'
  imageRepository: '<image-repository-name>'
  containerRegistry: '<container-registry-name>.azurecr.io'
  dockerfilePath: '$(Build.SourcesDirectory)/app/Dockerfile'
  tag: '$(Build.BuildId)'

  # Agent VM image name
  vmImageName: 'ubuntu-latest'

stages:
- stage: Build
  displayName: Build and push stage
  jobs:
  - job: Build
    displayName: Build
    pool:
      vmImage: $(vmImageName)
    steps:
    - task: Docker@2
      displayName: Build and push an image to container registry
      inputs:
        command: buildAndPush
        repository: $(imageRepository)
        dockerfile: $(dockerfilePath)
        containerRegistry: $(dockerRegistryServiceConnection)
        tags: |
          $(tag)

  7. Select Save and run and Save and run again.

  8. Select Job to view the logs and verify the pipeline ran successfully.

The Docker template creates the service connection to your Azure Container Registry and uses the Docker@2 task to build and push the Docker image to the 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.

Classic

Create a pipeline by using the classic editor

  1. From your Azure DevOps project, select Pipelines and New pipeline.

  2. Select Use the classic editor from the Where is your code? page.

  3. On the Select a source page, select GitHub.

  4. Choose your repository and select Continue.

  5. On the Select a template page, select Empty pipeline and Apply.

  6. Select ubuntu latest for the Agent Specification.

    :::image type="content" source="../media/classic-docker-pipeline-dialog.png" alt-text="Screenshot of classic Docker pipeline editor with ubuntu latest agent specification selected.":::

Add the Docker@2 task to the pipeline

Add a Docker@2 task to the pipeline to build and push the image to the container registry.

  1. Add a task to Agent job 1.

    :::image type="content" source="../media/classic-pipeline-add-task.png" alt-text="Screenshot of add task icon in the classic pipeline editor.":::

  2. Select the Docker task, and select Add.

  3. Select the buildAndPush task.

  4. Create a service connection by selecting +New.

    :::image type="content" source="../media/classic-pipeline-new-service-connection-selection.png" alt-text="Screenshot showing the +New button to create a new Azure Container Registry service connection in the Docker@2 task.":::

  5. Fill in the following fields:

    Field Description
    Subscription Select your Azure subscription.
    Azure container registry Select your Azure container registry.
    Service connection name Enter a name for the service connection.
    Grant access permission to all pipelines Select this option to grant access to all pipelines.

    :::image type="content" source="../media/classic-pipeline-new-azure-container-registry-service-connection-dialog.png" alt-text="Screenshot of the new Azure Container Registry service connection dialog showing fields for subscription, container registry, and service connection name.":::

  6. Select Save.

Run the pipeline

  1. Select Save and queue > Save and Queue.
  2. On the Run pipeline page, select Save and run.
  3. Select Job to view the logs and verify the pipeline ran successfully.

:::zone-end

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

Related articles