使用GitHub Actions推送受保护gh-pages分支时遇403权限错误

尝试通过GitHub Workflow更新受保护的gh-pages分支时遭遇403权限拒绝错误。已配置拥有workflow、repo权限的细粒度个人访问令牌（PAT），且本人为仓库管理员，但触发工作流后仍报错。

报错信息 #

/usr/bin/git push origin gh-pages
remote: Permission to dlt-science/science-notes.git denied to singhparshant.
fatal: unable to access 'https://github.com/dlt-science/science-notes.git/': The requested URL returned error: 403
Error: Action failed with "The process '/usr/bin/git' failed with exit code 128"

现有Workflow配置 #

name: deploy-book

# Only run this when the master branch changes
on:
  push:
    branches:
    - main
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - blogs/**

# This job installs dependencies, builds the book, and pushes it to `gh-pages`
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:
    - uses: actions/checkout@v2
      # with:
      #   persist-credentials: false
      #   fetch-depth: 0

    # Install dependencies
    - name: Set up Python 3.8
      uses: actions/setup-python@v2
      with:
        python-version: 3.8

    - name: Install dependencies
      run: |
        pip install -r requirements.txt

    # Build the book
    - name: Build the book
      run: |
        jupyter-book build blogs/

    # Push the book's HTML to gh-pages
    - name: GitHub Pages action
      uses: peaceiris/actions-gh-pages@v3.6.1
      with:
        github_token: ${{ secrets.PAT }}
        publish_dir: ./blogs/_build/html

• 确认细粒度PAT的权限与范围

  • 确保PAT是针对dlt-science/science-notes仓库创建的，而非全局或其他仓库
  • 检查PAT权限：必须开启Contents的Write权限（用于推送分支），同时确认Workflow权限已正确启用
  • 验证PAT未过期、未被撤销

• 修正checkout步骤配置
  取消actions/checkout@v2的注释，开启以下参数，避免默认GITHUB_TOKEN干扰自定义PAT：

  - uses: actions/checkout@v2
    with:
      persist-credentials: false
      fetch-depth: 0
  

  • persist-credentials: false：禁止将默认令牌存储在本地Git配置中，确保使用自定义PAT进行推送
  • fetch-depth: 0：完整拉取仓库历史，避免推送时因历史不完整导致的权限或冲突问题

• 检查gh-pages分支保护规则

  • 进入仓库Settings → Branches → Branch protection rules，找到gh-pages的规则
  • 确认是否允许管理员绕过分支保护；若开启了“Require pull request reviews before merging”，需调整规则允许自动化操作直接推送，或添加Workflow使用的PAT对应的账号到允许推送的列表

• 验证仓库Secret中的PAT正确性
  进入仓库Settings → Secrets and variables → Actions，检查名为PAT的Secret是否完整粘贴了细粒度令牌内容，无多余空格或换行

• 升级pages action版本
  当前使用的peaceiris/actions-gh-pages@v3.6.1版本较旧，建议升级至最新稳定版（如v4.x），避免版本兼容性问题导致的权限异常

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