Publishing Docker images

In this tutorial, you'll learn how to publish Docker images to a registry, such as Docker Hub or GitHub Packages, as part of your continuous integration (CI) workflow.

In this article

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.

Note

If you want to push to another third-party Docker registry, the example in the Publishing images to GitHub Packages section can serve as a good template.

Prerequisites

We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see Writing workflows.

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

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.

You can use pre-defined annotation keys to add metadata including a description, a license, and a source repository to your container image. For more information, see Working with the Container registry.

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

Note

Docker Hub normally imposes rate limits on both push and pull operations which will affect jobs on self-hosted runners. However, GitHub-hosted runners are not subject to these limits based on an agreement between GitHub and Docker.

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 published activity type.

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 Using secrets in GitHub Actions.

The metadata-action option required for Docker Hub is:

  • images: The namespace and name for the Docker image you are building/pushing to Docker Hub.

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