Publishing Docker images

Introduction

This guide shows you how to create a workflow that performs a Docker build, and then publishes Docker images to Docker Hub or GitHub Packages. With a single workflow, you can publish images to a single registry or to multiple registries.

Prerequisites

We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "Learn GitHub Actions."

You might also find it helpful to have a basic understanding of the following:

• "Encrypted secrets"
• "Authentication in a workflow"
• "Working with the Docker registry"

About image configuration

This guide assumes that you have a complete definition for a Docker image stored in a GitHub repository. For example, your repository must contain a Dockerfile, and any other files needed to perform a Docker build to create an image.

In this guide, we will use the Docker build-push-action action to build the Docker image and push it to one or more Docker registries. For more information, see build-push-action.

Publishing images to Docker Hub

Each time you create a new release on GitHub, you can trigger a workflow to publish your image. The workflow in the example below runs when the release event triggers with the created activity type. For more information on the release event, see "Events that trigger workflows.

In the example workflow below, we use the Docker login-action and build-push-action actions to build the Docker image and, if the build succeeds, push the built image to Docker Hub.

To push to Docker Hub, you will need to have a Docker Hub account, and have a Docker Hub repository created. For more information, see "Pushing a Docker container image to Docker Hub" in the Docker documentation.

The login-action options required for Docker Hub are:

• username and password: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as secrets so they aren't exposed in your workflow file. For more information, see "Creating and using encrypted secrets."

The build-push-action options required for Docker Hub are:

• tags: The tag of your new image in the format DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION. You can set a single tag as shown below, or specify multiple tags in a list.
• push: If set to true, the image will be pushed to the registry if it is built successfully.

name: Publish Docker image
on:
  release:
    types: [published]
jobs:
  push_to_registry:
    name: Push Docker image to Docker Hub
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v2
      - name: Log in to Docker Hub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Push to Docker Hub
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: my-docker-hub-namespace/my-docker-hub-repository:latest

The above workflow checks out the GitHub repository, uses the login-action to log in to the registry, and then uses the build-push-action action to build and push the Docker image. It tags the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a GitHub release, so the reference will be the Git tag for the release.

Publishing images to GitHub Packages

Each time you create a new release on GitHub, you can trigger a workflow to publish your image. The workflow in the example below runs when the release event triggers with the created activity type. For more information on the release event, see "Events that trigger workflows.

In the example workflow below, we use the Docker login-action and build-push-action actions to build the Docker image, and if the build succeeds, push the built image to GitHub Packages.

The login-action options required for GitHub Packages are:

• registry: Must be set to docker.pkg.github.com.
• username: You can use the ${{ github.actor }} context to automatically use the username of the user that triggered the workflow run. For more information, see "Context and expression syntax for GitHub Actions."
• password: You can use the automatically-generated GITHUB_TOKEN secret for the password. For more information, see "Authenticating with the GITHUB_TOKEN."

The build-push-action options required for GitHub Packages are:

• tags: Must be set in the format docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION. For example, for an image named octo-image stored on GitHub at http://github.com/octo-org/octo-repo, the tags option should be set to docker.pkg.github.com/octo-org/octo-repo/octo-image:latest. You can set a single tag as shown below, or specify multiple tags in a list.
• push: If set to true, the image will be pushed to the registry if it is built successfully.

name: Publish Docker image
on:
  release:
    types: [published]
jobs:
  push_to_registry:
    name: Push Docker image to GitHub Packages
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - name: Check out the repo
        uses: actions/checkout@v2
      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@v1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build container image
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: |
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.sha }}
            docker.pkg.github.com/${{ github.repository }}/octo-image:${{ github.ref }}

The above workflow checks out the GitHub repository, uses the login-action to log in to the registry, and then uses the build-push-action action to build and push the Docker image. It tags the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a GitHub release, so the reference will be the Git tag for the release.

Publishing images to Docker Hub and GitHub Packages

In a single workflow, you can publish your Docker image to multiple registries by using the login-action and build-push-action actions for each registry.

The following example workflow uses the steps from the previous sections ("Publishing images to Docker Hub" and "Publishing images to GitHub Packages") to create a single workflow that pushes to both registries.

name: Publish Docker image
on:
  release:
    types: [published]
jobs:
  push_to_registries:
    name: Push Docker image to multiple registries
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - name: Check out the repo
        uses: actions/checkout@v2
      - name: Log in to Docker Hub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@v1
        with:
          registry: docker.pkg.github.com
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Push to Docker Hub
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: my-docker-hub-namespace/my-docker-hub-repository:${{ github.ref }}
      - name: Build container image
        uses: docker/build-push-action@v2
        with:
          push: true
          tags: docker.pkg.github.com/${{ github.repository }}/my-image:${{ github.ref }}

The above workflow checks out the GitHub repository, uses the login-action twice to log in to both registries, and then uses the build-push-action action twice to build and push the Docker image to Docker Hub and GitHub Packages. For both steps, it tags the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a GitHub release, so the reference for both registries will be the Git tag for the release.