GitLab CI流水线出现detached head时如何正确执行git推送

初始分离头状态的成因 #

绝大多数CI平台（包括你使用的GitLab CI）默认拉取代码时会直接检出触发流水线对应commit的哈希值，不会创建并切换到对应的本地分支，这就是你第一次运行git status就显示detached HEAD的根本原因，属于平台默认行为，不是配置错误。

推送后semantic-release报错的成因 #

你添加git checkout main后本地已经切换到了正常的本地分支，但是推送操作存在逻辑漏洞，导致后续报错：

• 你使用带token的完整仓库地址直接推送，没有走本地配置的origin远程仓库，所以推送成功后本地存储的origin/main引用不会自动同步更新，还是停留在拉取代码时的旧commit，所以你会看到git status提示本地分支超前1个提交
• 如果你的构建阶段和semantic-release的发布阶段是两个独立的CI Job，同一条流水线的所有Job默认都是基于触发时的commit运行的，你在构建阶段往远端main分支推送了新的commit后，发布阶段拉取的仍然是旧的触发commit，所以发布阶段的本地main分支版本比远端低，就会触发本地分支main落后于远端分支，因此不会发布新版本的报错。

方案一：同Job执行所有操作（推荐） #

将生成文件、推送、semantic-release放在同一个CI Job内执行，调整配置如下：

before_script:
  - git config --global user.name "Bot"
  - git config --global user.email "ci@domain.com"
  - git checkout main
  # 直接更新origin远程地址为带token的地址，后续操作走origin即可同步本地引用
  - git remote set-url origin "https://git:${GIT_PUSH_TOKEN}@${CI_REPOSITORY_URL#*@}"
  - git pull origin main # 确保本地分支是最新状态
script:
  - npx ts-node ./generate.ts
  # 若你的generate.ts内未执行提交操作，需要补上以下两句
  - git add .
  - git commit -m "chore: auto generate files"
  - git push origin main
  # 直接在同一个Job内执行semantic-release，此时本地和远端分支状态完全同步
  - npx semantic-release

方案二：跨Job触发新流水线 #

如果必须分开构建和发布阶段，就在构建阶段推送新commit后，触发一条新的流水线执行semantic-release，不要在当前流水线的后续Job跑发布流程，新触发的流水线会拉取最新的main分支代码，不会出现分支落后的问题。

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