GitHub分支保护：如何兼顾人工PR要求与工作流推送权限

预期管控目标 #

• 所有人类用户对受保护分支的变更，必须通过提交PR发起，经代码评审、流水线校验通过后方可合并
• 负责新版本发布的GitHub Actions工作流，可直接在受保护分支上完成版本号递增、发布记录生成等发布相关操作

当前配置与故障表现 #

已完成的基础配置：

• 分支保护规则已开启「包含管理员（include administrators）」选项，所有人类账号（含管理员）均无法直接向受保护分支推送代码
• 测试工作流使用默认GITHUB_TOKEN鉴权，初始化日志显示Contents等核心操作权限均为write
  测试用工作流配置如下：

name: Build pipeline
"on":
  push:
    branches:
    - 'master'
defaults:
  run:
    shell: bash
jobs:
  release:
    runs-on:
    - self-hosted
    - default-runner
    needs: []
    steps:
    - name: Checkout code
      uses: actions/checkout@v2
      with:
        fetch-depth: 0
        clean: true
    - name: demo push
      if: github.ref == 'refs/heads/dev'
      run: |
        git config --global user.email "runner@xxx.com"
        git config --global user.name "Github Actions Runner"
        
        # normally we would generate the release notes here etc, increase the version,... though lets keep the example simple
        date >> test.txt
        git add test.txt
        git commit -m "test2" test.txt
        git push

故障现象：工作流执行推送操作时被分支保护规则拦截，报错信息如下：

remote: error: GH006: Protected branch update failed for refs/heads/dev.        
remote: error: You're not authorized to push to this branch. Visit https://docs.github.com/enterprise/3.2/articles/about-protected-branches/ for more information.        
 ! [remote rejected] dev -> dev (protected branch hook declined)
error: failed to push some refs to 'https://github.xxx.com/xx/xxx'

具体配置步骤 #

方案一：原生白名单配置（推荐，适用于支持该功能的GitHub版本） #

1. 进入仓库设置页，打开对应受保护分支的保护规则编辑界面
2. 找到允许绕过分支保护规则的用户、团队、应用配置项，在可选列表中搜索并添加GitHub Actions（部分旧版本显示为github-actions机器人账号）
3. 确认白名单中未添加任何人类用户账号，保存规则即可
   该配置生效后，所有使用默认GITHUB_TOKEN鉴权的工作流将获得受保护分支的直接推送权限，所有人类账号（包括管理员）仍然受分支保护规则约束，必须通过PR评审、CI校验流程才能合入代码。

方案二：专用机器账号PAT方案（适用于不支持原生Actions白名单的旧版GitHub Enterprise） #

如果当前使用的GitHub版本没有提供Actions白名单选项，可按以下步骤配置：

1. 创建专用的发布机器账号，不要使用个人日常使用的账号
2. 给该机器账号授予仓库写入权限，并将其添加到分支保护规则的绕过白名单中
3. 登录该机器账号，创建权限范围仅为repo -> Contents: read and write的个人访问令牌（PAT）
4. 将该PAT保存到目标仓库的Secrets中，命名为RELEASE_PAT
5. 修改工作流中的代码拉取步骤，使用该PAT代替默认GITHUB_TOKEN鉴权，修改后的checkout配置示例：

- name: Checkout code
  uses: actions/checkout@v2
  with:
    fetch-depth: 0
    clean: true
    token: ${{ secrets.RELEASE_PAT }}

注意事项：该PAT仅可在可信的发布类工作流中调用，禁止在PR触发的外部贡献者可执行的工作流中使用该凭证，避免权限泄露。

效果验证 #

配置完成后重新运行发布工作流，即可正常完成受保护分支的推送操作；同时所有人类用户尝试直接推送代码到受保护分支时，仍然会被分支保护规则拦截，必须提交PR完成评审、流水线校验流程后方可合入，符合预期管控要求。

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