CI/CD / 系统课时
给镜像生成可追踪的标签
给镜像生成可追踪的标签
容器镜像只使用 latest,很难回答“这个镜像来自哪个提交、哪次发布”。本节建立一套由分支、Git 标签和提交 SHA 共同组成的镜像标签策略,并在 GitHub Actions 中自动生成标签,让部署和回滚都能定位到具体源码版本。
学习目标
- 区分分支标签、发布标签和提交 SHA 标签的用途
- 使用 GitHub Actions 自动生成并写入镜像标签
- 根据部署与回滚需求选择稳定且可追踪的镜像引用
标签要同时解决可读性和唯一性
镜像标签承担两类职责。main、develop 这类分支标签便于表达“当前分支最新构建”,v1.4.0 这类 Git 标签适合对应正式发布;提交 SHA 则提供最精确的源码定位能力。
如果只发布 latest,后一次推送会覆盖前一次标签指向。出现故障时,即使知道生产环境使用过 latest,也无法仅凭这个标签确认当时对应哪个提交。因此生产流水线通常同时保留可变标签和不可变版本标识。

在工作流中生成标签
GitHub 官方的 docker/metadata-action 可以根据事件上下文生成镜像标签,避免自己编写复杂的 Bash 分支判断。下面是一个可直接放入工作流的核心示例;其中镜像名使用当前仓库名,登录和推送步骤可在实际发布工作流中另行配置。
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 会随实际运行变化。
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 步骤的片段示例。
- 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 标签回答“究竟是哪次提交”。三者职责分开后,镜像、源码和部署记录才能形成清晰的追踪关系。