使用GitHub Actions为Git仓库打标签时的Antora版本管理最佳实践

• 分支推送场景：GitHub Action可正常修改antora.yml版本为分支名并提交推送，无异常。
• 标签触发场景：Workflow运行在分离HEAD状态（标签指向单个commit而非分支），导致add-and-commit无法直接推送，抛出You are not currently on a branch错误。
• 核心需求：标签对应的构建版本需设为vX.X.X格式，main分支保留version: main，特性分支保留分支名版本，避免Antora构建出现重复导航报错。

通过创建临时分支解决分离HEAD的提交问题，无需复杂的分支清理流程，调整后的完整Workflow步骤如下：

# 特性分支处理：将版本替换为分支名（斜杠转下划线避免Antora兼容问题）
- name: Set version to branch name (feature branches)
  if: contains(github.ref, 'refs/heads/feat/')
  run: |
    BRANCH="${{ github.ref }}"
    BRANCH="${BRANCH//refs\/heads\//}"
    BRANCH="${BRANCH//\//__}"
    sed -i "s|version: main|version: $BRANCH|g" docs/antora.yml
    cat docs/antora.yml
  shell: bash

# main分支处理：强制重置为version: main
- name: Set version to 'main' (main branch)
  if: github.ref == 'refs/heads/main'
  run: |
    sed -i "/version: /s/.*/version: main/" docs/antora.yml
    cat docs/antora.yml
  shell: bash

# 标签场景专属处理：创建临时分支修改版本，更新标签指向
- name: Set version to tag name and update tag
  if: startsWith(github.ref, 'refs/tags/v')
  run: |
    # 提取纯标签名
    TAG_NAME="${{ github.ref }}"
    TAG_NAME="${TAG_NAME//refs\/tags\//}"
    
    # 基于当前分离HEAD创建临时分支
    TEMP_BRANCH="temp-tag-${TAG_NAME}"
    git checkout -b "$TEMP_BRANCH"
    
    # 修改antora.yml版本为标签号
    sed -i "/version: /s/.*/version: $TAG_NAME/" docs/antora.yml
    cat docs/antora.yml
    
    # 本地提交修改
    git config user.name "sebastian"
    git config user.email "sebastian@sommerfeld.io"
    git add docs/antora.yml
    git commit -m "[Actions Bot] refactor: set antora version to $TAG_NAME"
    
    # 推送临时分支到远程
    git push origin "$TEMP_BRANCH"
    
    # 强制将标签移动到新提交上
    git tag -f "$TAG_NAME"
    git push origin "$TAG_NAME" --force
    
    # 可选：删除远程临时分支（清理冗余分支）
    git push origin --delete "$TEMP_BRANCH"
  shell: bash

# 分支场景专属提交推送（与标签流程隔离，避免重复执行）
- name: Commit and push (branch only)
  if: startsWith(github.ref, 'refs/heads/')
  uses: EndBug/add-and-commit@v9
  with:
    author_name: sebastian
    author_email: sebastian@sommerfeld.io
    message: "[Actions Bot] refactor: set antora version to branchname"
    add: docs/antora.yml

1. 标签流程独立处理：放弃通用的add-and-commit，手动完成分支创建、版本修改、提交、推送、标签移动全流程，彻底规避分离HEAD的提交限制。
2. 标签更新逻辑：用git tag -f强制覆盖原有标签，让标签最终指向修改了版本的新提交，确保Antora构建时版本唯一。
3. 分支与标签隔离：分支场景继续使用add-and-commit简化流程，标签场景单独处理，避免逻辑冲突。

若不想创建临时分支，可在打标签前先通过Workflow将antora.yml版本修改为目标标签号并提交到main，打标签后再将版本改回version: main。但此方案会让main分支短暂出现标签版本号，不如临时分支方案干净。

• 确保Workflow拥有仓库读写权限（在仓库Settings的Actions权限中开启）。
• 标签覆盖操作（git push --force）会替换原有标签，若团队依赖标签历史需谨慎使用，或改为创建新标签而非覆盖。

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