GitHub Actions推送更新到GitHub报detached HEAD错误如何解决

actions/checkout@v2 默认检出逻辑不会切换到触发工作流的本地分支，而是直接拉取对应触发提交的Commit Hash，进入*分离头指针（detached HEAD）*状态。该状态下Git不绑定任何本地分支，直接执行git push就会抛出你碰到的错误。

报错中提示的git push origin HEAD:<name-of-remote-branch>写法虽然能强制把当前提交推到远程指定分支，但不会生成本地分支、也不会建立和远程分支的追踪关系，后续如果工作流还有其他Git操作很容易出问题，不建议用。

两种方案可选，优先推荐第一种，从检出阶段就避免分离头指针问题：

方案1：调整checkout动作参数（推荐） #

给checkout步骤补充显式分支配置，同时提前给工作流开仓库写入权限，避免push时403，完整可用配置如下：

# 工作流顶层配置写入权限
permissions:
  contents: write
jobs:
  version-bump:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          # 自动适配PR触发、普通分支推送触发两种场景，检出对应分支
          ref: ${{ github.event.pull_request.head.ref || github.ref_name }}
          fetch-depth: 0 # 拉取全量提交历史，替代默认浅克隆，避免提交计算异常
      - name: Commit new version
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          # 没有文件变更时跳过提交，防止空提交报错打断工作流
          git diff --cached --quiet || git commit -m "Bumping version number"
          git push

方案2：执行提交前手动切分支 #

如果不想改动checkout配置，直接在原有Git脚本最前面加一行分支切换命令即可，利用Actions内置的GITHUB_REF环境变量拿到当前分支名，从分离头状态切到对应分支：

- uses: actions/checkout@v2
  - name: Commit new version
    run: |
      # 解析内置环境变量拿到当前分支名，切换分支脱离分离头状态
      git checkout "${GITHUB_REF#refs/heads/}"
      git config --global user.name "github-actions[bot]"
      git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
      git add -A
      git diff --cached --quiet || git commit -m "Bumping version number"
      git push

注意：该方案同样需要在工作流顶层配置contents: write权限，否则推送会因权限不足失败。如果你的仓库开启了分支保护，需要提前给github-actions[bot]账号开放对应分支的写入权限。

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