简介
本指南介绍如何创建执行 Docker 构建的工作流程,然后将 Docker 映像发布到 Docker Hub 或 GitHub Packages。 通过单个工作流程,您可以将映像发布到单一注册表或多个注册表。
注意:如果你想推送到另一个第三方 Docker 注册表,“将映像发布到 GitHub Packages”部分中的示例可以用作一个很好的模板。
先决条件
建议基本了解工作流程配置选项和如何创建工作流程文件。 有关详细信息,请参阅“写入工作流”。
您可能还发现基本了解以下内容是有帮助的:
关于映像配置
本指南假定您对存储在 GitHub 仓库的 Docker 映像有完整的定义。 例如,存储库必须包含一个 Dockerfile,以及执行 Docker 构建以创建映像所需的任何其他文件。
可以使用预定义的注释键向容器映像添加元数据,包括说明、许可证和源存储库。有关详细信息,请参阅“使用容器注册表”。
在本指南中,我们将使用 Docker build-push-action
操作来构建 Docker 映像并将其推送到一个或多个 Docker 注册表。 有关详细信息,请参阅 build-push-action
。
将映像发布到 Docker Hub
每次在 GitHub Enterprise Cloud 上创建新版本时,都可以触发工作流来发布映像。 以下示例中的工作流在活动类型为 published
的 release
事件触发时运行。
在下面的示例工作流中,我们使用 Docker login-action
和 build-push-action
操作来构建 Docker 映像,如果构建成功,则将构建的映像推送到 Docker Hub。
要推送到 Docker Hub,您需要有一个 Docker Hub 帐户,并创建一个 Docker Hub 仓库。 有关详细信息,请参阅 Docker 文档中的“将 Docker 容器映像推送到 Docker Hub”。
Docker Hub 所需的 login-action
选项是:
username
和password
:这是 Docker Hub 用户名和密码。 我们建议将 Docker Hub 用户名和密码存储为机密,使它们不会公开在工作流程文件中。 有关详细信息,请参阅“在 GitHub Actions 中使用机密”。
Docker Hub 所需的 metadata-action
选项是:
images
:你正在构建/推送到 Docker Hub 的 Docker 映像的命名空间和名称。
Docker Hub 所需的 build-push-action
选项是:
tags
:你的新映像的标签,格式为DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION
。 您可以如下所示设置单个标记,或在列表中指定多个标记。push
:如果设置为true
,则映像将推送到注册表(如果成功构建)。
# 此工作流使用未经 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: ubuntu-latest permissions: packages: write contents: read attestations: write id-token: write steps: - name: Check out the repo uses: actions/checkout@v4 - name: Log in to Docker Hub uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 with: images: my-docker-hub-namespace/my-docker-hub-repository - name: Build and push Docker image id: push uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 with: context: . file: ./Dockerfile push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} - name: Generate artifact attestation uses: actions/attest-build-provenance@v1 with: subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} subject-digest: ${{ steps.push.outputs.digest }} push-to-registry: true
# 此工作流使用未经 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: ubuntu-latest
permissions:
packages: write
contents: read
attestations: write
id-token: write
steps:
- name: Check out the repo
uses: actions/checkout@v4
- name: Log in to Docker Hub
uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
with:
images: my-docker-hub-namespace/my-docker-hub-repository
- name: Build and push Docker image
id: push
uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
with:
context: .
file: ./Dockerfile
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
上述工作流签出 GitHub 存储库,使用 login-action
登录注册表,然后使用 build-push-action
操作:基于存储库的 Dockerfile
构建 Docker 映像;将映像推送到 Docker Hub,并向映像应用标签。
在最后一步中,它会为映像生成项目证明,从而提高供应链的安全性。 有关详细信息,请参阅“使用项目证明确立生成的来源”。
发布映像到 GitHub Packages
每次在 GitHub Enterprise Cloud 上创建新版本时,都可以触发工作流来发布映像。 以下示例中的工作流在将更改被推送到 release
分支时运行。
在下面的示例工作流中,我们使用 Docker login-action
、metadata-action
、和 build-push-action
操作来构建 Docker 映像,如果构建成功,则将构建的映像推送到 GitHub Packages。
GitHub Packages 所需的 login-action
选项是:
registry
:必须设置为ghcr.io
。username
:你可以使用${{ github.actor }}
上下文自动使用触发工作流运行的用户的用户名。 有关详细信息,请参阅“访问有关工作流运行的上下文信息”。password
:可以使用自动生成GITHUB_TOKEN
的密码机密。 有关详细信息,请参阅“自动令牌身份验证”。
GitHub Packages 所需的 metadata-action
选项是:
images
:正在构建的 Docker 映像的命名空间和名称。
GitHub Packages 所需的 build-push-action
选项是:
context
:将构建的上下文定义为位于指定路径中的文件集。push
:如果设置为true
,则映像将推送到注册表(如果成功构建)。tags
和labels
:它们由metadata-action
的输出填充。
注意:****
- 此工作流使用未通过 GitHub 认证的操作。 这些操作由第三方提供,并受单独的服务条款、隐私政策和支持文档的管辖。
- GitHub 建议将操作固定到提交 SHA。 若要获取较新版本,需要更新 SHA。 还可以引用标记或分支,但该操作可能会更改而不发出警告。
# name: Create and publish a Docker image # Configures this workflow to run every time a change is pushed to the branch called `release`. on: push: branches: ['release'] # Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds. env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} # There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu. jobs: build-and-push-image: runs-on: ubuntu-latest # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. permissions: contents: read packages: write attestations: write id-token: write # steps: - name: Checkout repository uses: actions/checkout@v4 # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. - name: Log in to the Container registry uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels. - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages. # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository. # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step. - name: Build and push Docker image id: push uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)." - name: Generate artifact attestation uses: actions/attest-build-provenance@v1 with: subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} subject-digest: ${{ steps.push.outputs.digest }} push-to-registry: true
name: Create and publish a Docker image
on:
push:
branches: ['release']
Configures this workflow to run every time a change is pushed to the branch called release
.
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
jobs:
build-and-push-image:
runs-on: ubuntu-latest
There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
permissions:
contents: read
packages: write
attestations: write
id-token: write
Sets the permissions granted to the GITHUB_TOKEN
for the actions in this job.
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Log in to the Container registry
uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
Uses the docker/login-action
action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
This step uses docker/metadata-action to extract tags and labels that will be applied to the specified image. The id
"meta" allows the output of this step to be referenced in a subsequent step. The images
value provides the base name for the tags and labels.
- name: Build and push Docker image
id: push
uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
This step uses the docker/build-push-action
action to build the image, based on your repository's Dockerfile
. If the build succeeds, it pushes the image to GitHub Packages.
It uses the context
parameter to define the build's context as the set of files located in the specified path. For more information, see "Usage" in the README of the docker/build-push-action
repository.
It uses the tags
and labels
parameters to tag and label the image with the output from the "meta" step.
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "使用项目证明确立生成的来源."
#
name: Create and publish a Docker image
# Configures this workflow to run every time a change is pushed to the branch called `release`.
on:
push:
branches: ['release']
# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
jobs:
build-and-push-image:
runs-on: ubuntu-latest
# Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
permissions:
contents: read
packages: write
attestations: write
id-token: write
#
steps:
- name: Checkout repository
uses: actions/checkout@v4
# Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
- name: Log in to the Container registry
uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
# This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
# It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
# It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
- name: Build and push Docker image
id: push
uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
# This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
上述工作流程通过推送到“发行版”分支触发。 它签出 GitHub 存储库,并使用 login-action
登录到 Container registry。 然后,它将提取 Docker 映像的标签和标记。 最后,它使用 build-push-action
操作构建映像并将其发布到 Container registry。
发布映像到 Docker Hub 和 GitHub Packages
在单个工作流中,你可以通过对每个注册表使用 login-action
和 build-push-action
操作将 Docker 映像发布到多个注册表。
以下示例工作流使用上述部分(“将映像发布到 Docker Hub”和“将映像发布到 GitHub Packages”)中的步骤创建推送到两个注册表的单个工作流。
# 此工作流使用未经 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: ubuntu-latest permissions: packages: write contents: read attestations: write id-token: write steps: - name: Check out the repo uses: actions/checkout@v4 - name: Log in to Docker Hub uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Log in to the Container registry uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Extract metadata (tags, labels) for Docker id: meta uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 with: images: | my-docker-hub-namespace/my-docker-hub-repository ghcr.io/${{ github.repository }} - name: Build and push Docker images id: push uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} - name: Generate artifact attestation uses: actions/attest-build-provenance@v1 with: subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} subject-digest: ${{ steps.push.outputs.digest }} push-to-registry: true
# 此工作流使用未经 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: ubuntu-latest
permissions:
packages: write
contents: read
attestations: write
id-token: write
steps:
- name: Check out the repo
uses: actions/checkout@v4
- name: Log in to Docker Hub
uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Log in to the Container registry
uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
with:
images: |
my-docker-hub-namespace/my-docker-hub-repository
ghcr.io/${{ github.repository }}
- name: Build and push Docker images
id: push
uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
- name: Generate artifact attestation
uses: actions/attest-build-provenance@v1
with:
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
上述工作流签出 GitHub Enterprise Cloud 存储库,使用 login-action
两次以登录到两个注册表,并使用 metadata-action
操作生成标记和标签。
然后,build-push-action
操作生成 Docker 映像并将其推送到 Docker Hub 和 Container registry。
在最后一步中,它会为映像生成项目证明,从而提高供应链的安全性。 有关详细信息,请参阅“使用项目证明确立生成的来源”。