GitHub Actions docker/metadata-action标签分配规则相关问题咨询

1. 标签规则表的含义与分配逻辑 #

你提到的表格是官方预设的事件-标签类型匹配规则，核心逻辑如下：

• 表格行代表 GitHub Workflow 的触发事件类型，包括推送分支、推送Tag、PR事件、定时任务、手动触发等
• 表格列代表支持生成的标签类型，包括语义化版本标签（semver）、分支名标签、edge 最新版标签、commit 哈希（sha）标签、PR编号标签等
• 单元格打勾代表对应事件触发时，该类型标签默认会被生成；空白项代表默认不生成
• 标签分配遵循优先级规则：越靠前定义的标签规则优先级越高，相同内容的标签会自动去重，不会重复生成

2. 配置项作用 #

你截图的配置项是该 Action 核心入参，主要作用如下：

• images：必填参数，指定要生成标签的 Docker 镜像仓库地址，所有生成的标签都会自动拼接该仓库前缀
• tags：核心规则配置项，每一条规则用type=开头指定生成逻辑，常见规则类型：
  • type=semver：根据推送的 Git Tag 语义化版本生成对应标签，比如v1.2.3会生成1.2.3、1.2、1三个层级的标签
  • type=sha：使用当前 commit 的短哈希作为标签
  • type=edge：推送到默认分支时生成edge标签，代表最新开发版本
  • type=ref,event=branch：直接使用当前分支名作为标签
  • type=ref,event=tag：直接使用推送的Git Tag名作为标签
• flavor：全局修饰配置，用于给所有生成的标签统一加前缀、后缀，比如加v前缀或者-alpine后缀
• labels：自定义 Docker 镜像的元数据标签，会自动附加到生成的镜像上

3. 仅生成sha标签的问题排查 #

出现该问题可按以下顺序排查原因：

• 触发事件不符合其他标签的生成条件：比如你是推送到非默认的普通分支，且未配置type=ref,event=branch规则，默认就只会生成sha标签；如果是推送Tag但Tag不符合语义化版本格式，semver类型的标签也不会生成
• 构建步骤未正确引用元数据输出：很多场景下是在 docker/build-push-action 步骤中，漏写了tags: ${{ steps.meta.outputs.tags }}配置，或者写错了metadata-action步骤的id，导致构建时没有拿到生成的标签列表，仅使用了默认的sha标签
• 标签被自动去重：如果配置了多条重复规则，或者不同规则生成了相同内容的标签，日志会输出所有候选规则条目，但实际推送时只会保留去重后的标签，看起来就像只有sha标签生效

内容的提问来源于stack exchange，提问作者tmp dev