Skip to main content

Publishing Docker images

You can publish Docker images to a registry, such as Docker Hub or GitHub Packages, as part of your continuous integration (CI) workflow.

注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

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 "Learn GitHub Actions."

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 Docker labels 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.

注意:your GitHub Enterprise Server instance 上的 GitHub Actions 对 GitHub.com 或 GitHub Marketplace 上的操作具有有限的访问权限。 有关详细信息,请参阅“管理对 GitHub.com 上操作的访问”并联系 GitHub Enterprise 站点管理员。

Publishing images to Docker Hub

每次在 GitHub Enterprise Server 上创建新版本时,都可以触发工作流来发布映像。 以下示例中的工作流在活动类型为 createdrelease 事件触发时运行。 有关 release 事件的详细信息,请参阅“触发工作流的事件”。

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 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:

  • 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.
YAML
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registry:
    name: Push Docker image to Docker Hub
    runs-on: [self-hosted]
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3
      
      - name: Log in to Docker Hub
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
        with:
          images: my-docker-hub-namespace/my-docker-hub-repository
      
      - name: Build and push Docker image
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

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 a Docker image based on your repository's Dockerfile; push the image to Docker Hub, and apply a tag to the image.

Publishing images to GitHub Packages

注意:GitHub Enterprise Server 的 Container registry 当前为 beta 版本,可能会有变化。

必须启用 GitHub Packages 和子域隔离才能使用 Container registry。 有关详细信息,请参阅“使用容器注册表”。

每次在 GitHub Enterprise Server 上创建新版本时,都可以触发工作流来发布映像。 以下示例中的工作流在活动类型为 createdrelease 事件触发时运行。 有关 release 事件的详细信息,请参阅“触发工作流的事件”。

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 containers.HOSTNAME.
  • 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 "Contexts."
  • 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:

  • push: If set to true, the image will be pushed to the registry if it is built successfully.

  • tags: Must be set in the format containers.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION.

    For example, for an image named octo-image stored on GitHub Enterprise Server at https://HOSTNAME/octo-org/octo-repo, the tags option should be set to containers.HOSTNAME/octo-org/octo-repo/octo-image:latest. You can set a single tag as shown below, or specify multiple tags in a list.

YAML
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。

name: Create and publish a Docker image

on:
  push:
    branches: ['release']

env:
  REGISTRY: containers.HOSTNAME
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push-image:
    runs-on: [self-hosted]
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Log in to the Container registry
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

The above workflow is triggered by a push to the "release" branch. It checks out the GitHub repository, and uses the login-action to log in to the Container registry. It then extracts labels and tags for the Docker image. Finally, it uses the build-push-action action to build the image and publish it on the Container registry.

Publishing images to Docker Hub and GitHub Packages

注意:GitHub Enterprise Server 的 Container registry 当前为 beta 版本,可能会有变化。

必须启用 GitHub Packages 和子域隔离才能使用 Container registry。 有关详细信息,请参阅“使用容器注册表”。

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.

YAML
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本,需要更新 SHA。
# 还可以引用标记或分支,但该操作可能会更改而不发出警告。

name: Publish Docker image

on:
  release:
    types: [published]

jobs:
  push_to_registries:
    name: Push Docker image to multiple registries
    runs-on: [self-hosted]
    permissions:
      packages: write
      contents: read
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3
      
      - name: Log in to Docker Hub
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Log in to the Container registry
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          registry: containers.HOSTNAME
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
        with:
          images: |
            my-docker-hub-namespace/my-docker-hub-repository
            containers.HOSTNAME/${{ github.repository }}
      
      - name: Build and push Docker images
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

The above workflow checks out the GitHub Enterprise Server repository, uses the login-action twice to log in to both registries and generates tags and labels with the metadata-action action. Then the build-push-action action builds and pushes the Docker image to Docker Hub and the Container registry.