GitHub Actions发布工作流中github.ref_name标签偶现为空的问题

可能的原因 #

• GitHub事件元数据同步延迟：当release: published事件触发时，GitHub后台可能还未完全完成标签（tag）的元数据同步，此时Actions上下文里的github.ref_name还未被正确填充，导致获取到空值。这种异步同步的延迟是偶发问题的核心原因。
• 特殊发布创建流程的影响：如果是通过API、自动化脚本快速创建release，可能会在标签还未完全落地到仓库refs目录时就触发了Actions工作流，进而导致ref_name为空。
• GitHub Actions上下文偶发异常：极个别情况下，GitHub的Actions运行环境可能出现上下文变量未正确注入的小概率故障，不过这种情况非常少见，重新执行即可恢复。

解决办法 #

1. 替换为更可靠的tag来源 #

直接使用github.event.release.tag_name替代github.ref_name，因为release事件的payload里直接包含了发布的标签名，不需要依赖ref的同步，更稳定：

env:
  DOCKER_TAG: ${{ github.event.release.tag_name }}

2. 增加标签非空检查 #

在执行Docker命令前添加检查步骤，确保标签不为空，提前终止工作流并给出明确提示：

- name: Validate Docker tag
  run: |
    if [ -z "${DOCKER_TAG}" ]; then
      echo "Error: Docker tag is empty!"
      exit 1
    fi
  env:
    DOCKER_TAG: ${{ github.event.release.tag_name }}

3. 可选：添加重试机制 #

如果同步延迟是主要问题，可以给工作流添加重试策略，在失败时自动重试：

jobs:
  generate:
    name: Create release docker image
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      retry: 2  # 最多重试2次

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