本地触发Github Actions时提交信息无法正确显示分支名求助

核心原因 #

你从本地触发工作流时，大概率是误指定了tag作为触发的ref而非分支ref。这会导致GITHUB_REF、github.ref_name这些上下文变量指向tag名称，自然和TAG_NAME一致，无法正确获取分支名。

解决方案 #

1. 触发工作流时明确指定分支 #

使用gh命令触发时，必须通过--ref参数指定目标分支，而非tag：

gh workflow run <你的工作流文件名> --ref <目标分支名>

示例：

gh workflow run deploy.yml --ref main

这样github.ref_name就会正确返回分支名，而非tag名。

2. 工作流内增加分支判断（可选） #

如果需要兼容分支和tag两种触发场景，或者防止误触发导致提交失败，可以在commit步骤里加入bash逻辑，仅在分支场景下提取分支名：

- name: Commit files
  run: |
    git config --local user.email github.actions@domain.com 
    git config --local user.name "username"
    git add -A
    if ! git diff-index --quiet HEAD; then
      # 仅当当前ref是分支时提取分支名
      BRANCH_NAME=""
      if [[ "$GITHUB_REF" == refs/heads/* ]]; then
        BRANCH_NAME="${GITHUB_REF#refs/heads/}"
      fi
      # 分支名存在才提交，避免失败
      if [[ -n "$BRANCH_NAME" ]]; then
        git commit -am "$BRANCH_NAME ${{ env.TAG_NAME }} on ${{ env.CLUSTER_ENV }}"
        git push
      else
        echo "Error: 未获取到分支名，终止提交"
        exit 1
      fi
    fi

3. 通过工作流输入参数手动传入分支名（兜底方案） #

如果上述方法仍有问题，可以在工作流中定义必填输入参数，触发时手动传入分支名：
首先在工作流开头添加触发配置：

on:
  workflow_dispatch:
    inputs:
      target_branch:
        description: '分支名称（用于提交信息）'
        required: true

然后在commit步骤中使用该输入值：

- name: Commit files
  run: |
    git config --local user.email github.actions@domain.com 
    git config --local user.name "username"
    git add -A
    if ! git diff-index --quiet HEAD; then
      git commit -am "${{ github.event.inputs.target_branch }} ${{ env.TAG_NAME }} on ${{ env.CLUSTER_ENV }}"
      git push
    fi

触发时通过命令行传入分支名：

gh workflow run <工作流文件名> -f target_branch=main

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