GitHub Actions更新autogen-docs分支后GitHub Pages未更新的问题咨询

问题根源 #

你当前的脚本通过强制删除重建分支并推送的方式更新文档，这种操作可能无法触发GitHub Pages的自动构建机制——GitHub对强制推送的分支变更，有时不会触发Pages的构建钩子，导致页面不更新。

可行解决方案 #

1. 改用增量提交，避免强制覆盖分支

放弃删除重建分支的操作，直接在autogen-docs分支上更新内容，正常推送而非强制推送，这样能确保触发Pages的构建触发器：
修改后的Workflow步骤如下：

update-docs:
  name : Update docs
  runs-on: [ docker-runner ]
  steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
        # 直接检出autogen-docs分支，如果不存在则创建
        ref: autogen-docs

    - uses: ./.github/actions/setup-env
      with:
        environment: dev

    - name: Generate docs
      run: |
        git config user.name github-actions
        git config user.email github-actions@github.com

        rm -rf ./docs 
        poetry run python ./my_pkg/auto_docs/generate_docs.py

        # 检查是否有变更
        if git diff --quiet; then
          echo "No docs changes to commit"
          exit 0
        fi

        git add -A docs
        git commit -m "docs update: auto-generated from CI"
        git push origin autogen-docs

2. 强制推送后手动触发Pages构建

如果必须保留强制覆盖分支的逻辑，可以在推送后通过GitHub API手动触发Pages构建，需要添加相应权限：
首先在Workflow开头添加权限配置：

permissions:
  pages: write
  id-token: write

然后在推送步骤后添加触发命令：

git push -f origin autogen-docs

# 调用API触发Pages构建
curl -L \
  -X POST \
  -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/${{ github.repository }}/pages/builds

3. 验证构建状态

前往仓库的「Settings」→「Pages」→「Build and deployment」，查看最近的构建记录，确认是否有触发构建，以及是否存在构建失败的具体原因。

4. 确保提交有有效变更

确认生成的docs文件夹确实有内容变化，避免空提交或无意义的提交——GitHub Pages可能会忽略无实际文件变更的提交。

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