使用docker/metadata-action无法获取正确Docker镜像标签的问题

以下是导致docker/metadata-action未生成Git版本标签的常见原因及对应修复方案：

1. Checkout步骤未拉取完整标签信息 #

默认的actions/checkout仅拉取当前分支的最新提交（fetch-depth: 1），无法获取仓库中的标签历史，导致metadata-action无法检测到当前提交关联的Git标签。

修复方案：修改checkout步骤，拉取完整仓库历史：

- name: Checkout code
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 拉取所有提交历史与标签

2. metadata-action的tags规则缺失标签捕获配置 #

如果仅配置了分支标签规则，自然不会生成版本标签。需要明确添加匹配Git标签的规则。

修复方案：补充tags配置，同时包含分支和标签规则：

- name: Generate Docker metadata
  uses: docker/metadata-action@v5
  id: meta
  with:
    images: your-registry/your-image-name
    tags: |
      # 生成分支标签（如main）
      type=ref,event=branch
      # 生成不带v前缀的SemVer标签（如v1.2.3 → 1.2.3）
      type=semver,pattern={{version}}
      # 可选：保留标签的v前缀（如v1.2.3 → v1.2.3）
      # type=ref,event=tag

3. Workflow触发条件未包含标签推送事件 #

若你的Workflow仅监听main分支的推送，Semantic Release推送标签时不会触发Workflow，只有分支更新时才会运行，此时metadata-action只能检测到分支标签。

修复方案（若使用push触发而非workflow_run）：扩展触发条件，包含标签推送：

on:
  push:
    branches: [main]
    tags: [v*]  # 匹配所有以v开头的版本标签

4. 验证标签关联状态 #

可添加一个调试步骤，确认当前提交是否关联了目标标签：

- name: Check tags for current commit
  run: git tag --points-at HEAD

如果该步骤能输出对应的版本标签，说明仓库状态正常，问题集中在metadata-action的配置上；若无输出，需检查Semantic Release是否正确将标签打在main分支的最新提交上。

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