如何通过Github Actions将pdoc HTML文档部署至Github仓库docs目录

你可以在现有Workflow中添加一个部署任务，完成从Artifact下载文档、提交并推送到目标分支的操作。以下是修改后的完整配置：

name: documentation

on:
  push:
    branches:
      - dev
  pull_request:
    branches:
      - "dev"

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11.4'

      - run: pip install -e .
      - run: pdoc --html package_name --html-dir docs --force

      - uses: actions/upload-artifact@v4
        with:
          name: docs_data
          path: docs/
          if-no-files-found: warn
          overwrite: true

  deploy:
    needs: build
    runs-on: ubuntu-latest
    # 仅在push到dev，或同一仓库内的PR触发时执行（避免fork的PR无权限推送）
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: 检出目标分支
        uses: actions/checkout@v4
        with:
          # push事件用当前分支（dev），PR事件用PR的源分支
          ref: ${{ github.event_name == 'push' && github.ref_name || github.head_ref }}
          fetch-depth: 0 # 拉取完整历史，避免提交冲突

      - name: 下载文档Artifact
        uses: actions/download-artifact@v4
        with:
          name: docs_data
          path: ./docs/ # 直接覆盖到仓库的docs目录

      - name: 配置Git环境
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: 提交并推送文档更新
        run: |
          # 检查是否有文件变化，避免空提交
          git add docs/
          if ! git diff --quiet && ! git diff --staged --quiet; then
            git commit -m "chore: auto-update documentation"
            git push
          fi

关键说明 #

• 任务依赖：deploy任务依赖build任务，确保文档生成完成后才执行部署
• 分支处理：
  • 当push到dev分支时，直接将文档提交到dev分支的docs/目录
  • 当发起PR到dev时，将文档提交到PR的源分支（比如你从feature/doc-update发起PR，文档会更新到这个分支），PR会自动同步更新
• Git配置：使用GitHub官方Bot账号提交，避免权限和身份验证问题
• 空提交规避：仅在文档有实际变化时才提交，避免无意义的空提交

注意事项 #

• 如果你的docs/目录包含非自动生成的文件，需要调整pdoc的输出路径（比如输出到docs/generated/），避免覆盖手动维护的文件
• 若允许外部fork的PR触发部署，需要额外配置仓库权限（不推荐私有仓库开启此设置）

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