GitHub Actions：从私有仓库推送到公有仓库失败求助

一、PAT相关遗漏配置 #

• 权限范围不足：确认PAT勾选了repo全权限（含公有仓库）和workflow权限，且未设置仓库范围限制（选特定仓库会无法访问同组织其他仓库）。
• Secrets存储错误：私有仓库的Secrets必须正确添加该PAT，工作流中推送URL要写成https://${{ secrets.YOUR_PAT_NAME }}@github.com/ORG/REPO.github.io.git，确保引用的Secrets名称一致。
• 组织级权限限制：检查组织「Settings > Security > Personal access tokens」，确认允许PAT访问组织仓库，无IP限制或审批规则拦截。

二、SSH密钥配置遗漏点 #

• 公钥未开写权限：SSH公钥要添加到公有Pages仓库的「Settings > Deploy keys」，必须勾选「Allow write access」（默认只读，这是高频遗漏项）。
• 私钥存储与加载错误：私钥需完整复制（包含首尾标识行）存入私有仓库Secrets，工作流中要配置SSH代理加载，示例代码：

  - name: 配置SSH
    env:
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
    run: |
      mkdir -p ~/.ssh
      echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
      chmod 600 ~/.ssh/id_rsa
      ssh-keyscan github.com >> ~/.ssh/known_hosts
  

• 推送URL未切换为SSH格式：工作流里的推送地址必须是git@github.com:ORG/REPO.github.io.git，用HTTPS格式会默认使用无权限的github-actions[bot]。

三、GitHub Actions权限配置遗漏 #

• 工作流权限不完整：在工作流jobs上方或具体job中添加权限配置：

  permissions:
    contents: write
    pages: write
    id-token: write
  

  同时检查公有Pages仓库「Settings > Actions > General > Workflow permissions」，设置为「Read and write permissions」。
• 未使用组织级认证方式：若组织权限管控严格，个人PAT可能受限，可创建组织级GitHub App，分配两个仓库的读写权限，用App密钥在工作流中认证。

四、其他易忽略点 #

• 分支保护规则拦截：检查公有Pages仓库目标分支（如main/gh-pages）的分支保护规则，确认允许部署密钥或PAT对应的账号推送，必要时临时关闭测试。
• 未替换默认bot身份：github-actions[bot]仅拥有私有仓库权限，跨仓库推送必须用PAT/SSH密钥覆盖默认身份，确保所有推送操作使用自定义认证。

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