Git Describe在本地与GitHub Actions Runner中输出不一致问题排查

问题概述 #

测试分支存在标签v33.4.0，在本地Windows（Git 2.41.0.windows.1）和Docker Ubuntu（Git 2.34.1）执行命令：

git describe 26888c716fd70bde90c73ed603134bd1162018c6 --abbrev=7 --match="v33.4.*" --always

得到预期输出v33.4.0-5-g26888c7；但在GitHub Actions（Git 2.41.0）中执行相同命令（set -x显示命令为git describe 26888c716fd70bde90c73ed603134bd1162018c6 --abbrev=7 '--match=v33.4.*' --always），输出为26888c7。

排查方向 #

1. GitHub Actions 拉取仓库时未获取完整标签 #

GitHub Actions 默认的actions/checkout动作如果未配置fetch-depth参数，只会拉取最新一次提交的浅克隆（shallow clone），这种情况下仓库本地不存在完整的标签历史，git describe找不到匹配的标签，就会输出提交哈希短码。

验证解决：在checkout步骤添加参数：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 拉取完整仓库历史，包括所有标签

2. 标签类型导致的识别问题 #

git describe默认只识别附注标签（annotated tags），如果v33.4.0是轻量标签（lightweight tag），需要添加--tags参数才能让命令识别到该标签：

git describe 26888c716fd70bde90c73ed603134bd1162018c6 --abbrev=7 --match="v33.4.*" --always --tags

可在本地测试该命令，若加上--tags才得到预期结果，说明GitHub Actions环境中默认未识别轻量标签。

3. 提交哈希的分支归属问题 #

确认26888c716fd70bde90c73ed603134bd1162018c6这个提交是否在GitHub Actions拉取的当前分支历史中。如果工作流切换到了其他分支，而该提交不在当前分支的历史链上，git describe无法找到关联标签，就会输出哈希。

验证命令：

git branch --contains 26888c716fd70bde90c73ed603134bd1162018c6

若没有输出当前分支，说明提交不在当前分支历史范围内。

4. 通配符匹配的shell解析差异 #

虽然set -x显示--match参数被单引号包裹，但可尝试用精确匹配标签替代通配符，验证是否是通配符解析问题：

git describe 26888c716fd70bde90c73ed603134bd1162018c6 --abbrev=7 --match='v33.4.0' --always

若该命令能得到正确结果，说明通配符匹配在当前GitHub Actions的shell环境中未命中目标标签。

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