GitHub Actions部署GitHub Pages失败：gh-pages分支未自动创建

• 检查仓库Workflow权限
  进入mainproject仓库的「Settings」→「Actions」→「General」，找到「Workflow permissions」区域，确认已勾选「Read and write permissions」并保存。若权限为只读，GitHub Actions无法创建新的gh-pages分支。

• 查看Actions运行日志
  打开mainproject仓库的「Actions」页面，找到sphinx.yml对应的工作流记录，点击进入查看详细日志。重点排查部署步骤的报错信息，比如认证失败、构建产物路径错误、脚本执行异常等，这些都会直接导致分支无法生成。

• 核对sphinx.yml配置细节
  对比testdocs和mainproject的sphinx.yml文件，重点确认部署相关配置：

  • 确认使用的部署Action（如peaceiris/actions-gh-pages）版本完全一致
  • 检查认证凭据（如deploy_key或personal_token）是否已正确添加到mainproject仓库的「Settings」→「Secrets and variables」→「Actions」中
  • 确认Sphinx构建产物的输出路径（如_build/html）与部署Action的publish_dir参数匹配

• 排查仓库类型限制
  如果mainproject是组织仓库，需确认组织管理员是否开启了GitHub Actions的分支创建权限；如果是私有仓库，检查GitHub Pages对私有仓库的支持是否正常（GitHub Pages支持私有仓库部署，但需对应权限）。

• 重新触发工作流
  进入mainproject仓库的「Actions」页面，找到对应的sphinx.yml工作流，点击「Re-run jobs」重新执行一次，排除首次运行时的缓存或临时网络问题。

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