CI/CD / 系统课时

给镜像生成可追踪的标签

给镜像生成可追踪的标签

容器镜像只使用 latest,很难回答“这个镜像来自哪个提交、哪次发布”。本节建立一套由分支、Git 标签和提交 SHA 共同组成的镜像标签策略,并在 GitHub Actions 中自动生成标签,让部署和回滚都能定位到具体源码版本。

学习目标

  • 区分分支标签、发布标签和提交 SHA 标签的用途
  • 使用 GitHub Actions 自动生成并写入镜像标签
  • 根据部署与回滚需求选择稳定且可追踪的镜像引用

标签要同时解决可读性和唯一性

镜像标签承担两类职责。main、develop 这类分支标签便于表达“当前分支最新构建”,v1.4.0 这类 Git 标签适合对应正式发布;提交 SHA 则提供最精确的源码定位能力。

如果只发布 latest,后一次推送会覆盖前一次标签指向。出现故障时,即使知道生产环境使用过 latest,也无法仅凭这个标签确认当时对应哪个提交。因此生产流水线通常同时保留可变标签和不可变版本标识。

分支、Git 标签与提交 SHA 映射到镜像标签

在工作流中生成标签

GitHub 官方的 docker/metadata-action 可以根据事件上下文生成镜像标签,避免自己编写复杂的 Bash 分支判断。下面是一个可直接放入工作流的核心示例;其中镜像名使用当前仓库名,登录和推送步骤可在实际发布工作流中另行配置。

yaml
name: image-metadata

on:
  push:
    branches:
      - main
    tags:
      - 'v*'

jobs:
  metadata:
    runs-on: ubuntu-latest
    steps:
      - name: Generate image metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=ref,event=tag
            type=sha,prefix=sha-

      - name: Show generated tags
        env:
          IMAGE_TAGS: ${{ steps.meta.outputs.tags }}
        run: printf '%s\n' "$IMAGE_TAGS"

预期输出

当 main 上某次提交触发工作流时,输出形式类似下面内容;仓库名和 SHA 会随实际运行变化。

text
ghcr.io/<OWNER>/<REPOSITORY>:main
ghcr.io/<OWNER>/<REPOSITORY>:sha-<SHA>

当推送符合规则的 Git 标签(例如 v1.4.0)时,会生成对应的 v1.4.0 标签,并同时生成 SHA 标签。<OWNER>、<REPOSITORY> 和 <SHA> 均代表实际运行时的动态值。

把标签交给镜像构建步骤

生成元数据后,不要重新拼接另一套标签规则。构建步骤直接消费 steps.meta.outputs.tags,这样“生成什么标签”和“推送什么标签”保持一致。以下为依赖前述 meta 步骤的片段示例。

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

这是配置片段,不单独运行;它还依赖 Dockerfile、镜像仓库登录以及前面的 meta 步骤。生效后,同一次构建可以被多个标签引用,而不是为每个标签重复构建镜像。验证时可在目标容器仓库中检查该版本是否同时出现预期的分支、Git 标签或 SHA 标签。

部署时优先保留精确版本

分支标签适合持续集成环境,因为 main 会随着新提交不断移动;正式发布可以使用 v1.4.0 这样的版本标签表达业务版本,同时保留 SHA 标签建立源码追踪链路。需要精确复现或回滚时,应使用不会因后续提交而自然移动的版本引用。

一套实用策略并不需要大量标签:分支标签回答“这条开发线当前是什么”,Git 标签回答“发布了哪个版本”,SHA 标签回答“究竟是哪次提交”。三者职责分开后,镜像、源码和部署记录才能形成清晰的追踪关系。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给镜像生成可追踪的标签

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通