ReadTheDocs构建失败：尝试拉取不存在的master分支问题

问题原因 #

ReadTheDocs尝试拉取master分支通常源于以下几种情况：

• 项目初始导入时，RTD缓存了旧的分支配置（比如仓库曾有master分支，后续改为main但RTD未同步更新）
• RTD未正确获取仓库最新分支列表，导致默认分支下拉菜单为空，无法修改
• 权限同步不及时，ReadTheDocs应用无法读取仓库的分支信息

解决步骤 #

1. 手动添加并设置默认分支 #

进入项目的「Versions」页面：

• 点击「Add version」按钮
• 在弹窗中输入main作为分支名，勾选「Active」和「Default」选项
• 保存后重新触发构建，此时RTD会尝试拉取main分支

2. 清理缓存并同步仓库 #

• 进入项目的「Admin」→「Advanced Settings」页面
• 找到「Clear cache」选项，点击清理缓存
• 返回项目主页，点击「Sync repository」按钮，强制RTD拉取最新的仓库分支信息

3. 重新确认GitHub权限 #

• 登录GitHub，进入组织的「Settings」→「Applications」→「Installed GitHub Apps」
• 找到「Read the Docs Community」应用，确认它拥有目标仓库的「Read access to code and metadata」权限
• 若权限异常，重新授权应用，确保权限覆盖目标仓库

4. 极端情况：重新导入项目 #

如果以上方法均无效，可尝试删除现有RTD项目后重新导入：

• 删除前备份好构建配置文件（如readthedocs.yaml）
• 重新导入时，确认选择main作为默认分支

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