为何GitHub Workflow无法识别推送的Git带注释标签？如何修复？

本地操作与结果 #

本地执行以下命令查看标签：

git for-each-ref \
  --format="%(if:equals=tag)%(objecttype)%(then)a %(else)%(if:equals=blob)%(objecttype)%(then)b %(else)  %(end)%(end)%(align:20,right)%(refname:short)%09%(objectname:short)%(end)%09%(if:equals=tag)%(objecttype)%(then)@%(object) %(contents:subject)%(else)%(end)" \
  --sort=taggerdate \
  refs/tags \
| tail -n2

得到结果：

a       v0.11.0 a385a1c @2c3ef8cdb5068e47f818af0c2bb81c5a6a2b2056 0.11.0
a       v0.11.1 55210a6 @9b389a86652517a49c025c40a2cd7bd614d3ace4 0.11.1

GitHub Actions中的表现 #

推送v0.11.1标签触发的Workflow中，执行相同命令得到：

a       v0.10.0 b2e1fd0 @b746724eb7f2adbd254ebe66219d83fbad411326 0.10.0
a       v0.11.0 a385a1c @2c3ef8cdb5068e47f818af0c2bb81c5a6a2b2056 0.11.0

可见v0.11.1标签未被识别。

标签创建与推送方式 #

本地通过以下命令创建并推送标签：

make release semver=0.11.1 || make rollback tag=v0.11.1

对应的Makefile配置：

.PHONY: release
release: pre-release gh-release

pre-release:
    $(call check_defined, semver)
    $(info Attempting to release $(semver))
    ./gradlew build --quiet
    git tag -m $(semver) -a v$(semver)
    ./gradlew assemble shadowJar --quiet
    ./gradlew publishPlugins --validate-only --no-configuration-cache --warn

gh-release: build/libs/*.jar
    $(call check_defined, semver)
    git push --tags

GitHub Workflow配置 #

name: Release
on:
  push:
    tags:
      - "v*.*.*"
jobs:
  publish:
    runs-on: ubuntu-latest  
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

问题原因 #

1. 推送顺序逻辑缺陷：
   Makefile中仅推送标签但未确保标签指向的本地提交已同步到GitHub。若标签创建前的代码提交未推送，GitHub上的标签会指向不存在的提交；即便提交已存在，也可能因推送时序差出现同步延迟，导致Actions无法识别标签。

2. Actions拉取标签的潜在问题：
   即便设置了fetch-depth: 0，在push tags触发的事件中，actions/checkout@v4默认会checkout到触发Workflow的标签对应提交，可能未完整拉取所有标签，导致环境缺失最新标签。

3. 标签创建命令的隐患：
   git tag -m $(semver)未用引号包裹注释内容，若版本号包含特殊字符（如+），会导致注释格式异常，标签状态出错。

修复方案 #

1. 调整推送顺序，确保提交先同步 #

修改Makefile，在创建标签前先推送本地提交，同时用引号包裹标签注释避免格式问题：

.PHONY: release
release: pre-release push-commits gh-release

pre-release:
    $(call check_defined, semver)
    $(info Attempting to release $(semver))
    ./gradlew build --quiet
    # 先推送最新代码到远程仓库
    git push origin HEAD
    # 用引号包裹注释，避免特殊字符干扰
    git tag -a v$(semver) -m "$(semver)"
    ./gradlew assemble shadowJar --quiet
    ./gradlew publishPlugins --validate-only --no-configuration-cache --warn

push-commits:
    git push origin HEAD

gh-release: build/libs/*.jar
    $(call check_defined, semver)
    git push --tags

2. 强制拉取所有标签到Actions环境 #

在Workflow的checkout步骤后添加显式拉取标签的命令，确保环境包含所有远程标签：

name: Release
on:
  push:
    tags:
      - "v*.*.*"
jobs:
  publish:
    runs-on: ubuntu-latest  
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # 显式拉取所有远程标签
      - name: Fetch all remote tags
        run: git fetch origin --tags

3. 验证标签状态（可选） #

在Workflow中添加标签验证步骤，确认标签已被正确拉取：

- name: Verify tags
  run: git for-each-ref refs/tags --sort=taggerdate | tail -n2

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