ReadTheDocs多项目构建异常：旧项目Stable版本关联无效SHA

我之前处理过类似的配置场景，给你梳理几个关键步骤来修复这个问题：

• 第一步：确认项目仓库配置已完全更新
  先进入旧仓库对应的ReadTheDocs项目的「Admin」页面，找到「Repository」选项卡，仔细核对：

  • 仓库URL是否已经替换为目标GitHub仓库地址
  • 「Default branch」是否设置为你当前使用的分支（比如main或master）
  • 确保「Repository type」选择的是GitHub，且授权状态有效

• 第二步：重置Stable版本的关联提交
  进入项目的「Versions」选项卡，找到标记为「Stable」的版本：

  1. 点击该版本右侧的「Edit」按钮
  2. 在「Version details」页面，有两种方式重置关联：
     • 选择「Use latest commit from branch」，然后挑选正确的目标分支
     • 或者手动输入新仓库中存在的有效SHA值
  3. 保存设置后，点击「Build version」触发一次手动构建，验证是否能正常拉取代码

• 第三步：检查Webhook的触发逻辑
  虽然你已经添加了两个Webhook，但要确保旧项目的Webhook是监听新仓库的事件：

  • 进入GitHub仓库的「Settings」→「Webhooks」，找到对应旧ReadTheDocs项目的Webhook
  • 检查「Which events would you like to trigger this webhook?」是否勾选了正确的事件（比如「Just the push event」）
  • 可以点击「Redeliver」按钮重新发送一次测试事件，确认ReadTheDocs能正确接收并触发构建

• 第四步：清除ReadTheDocs缓存（若上述步骤无效）
  如果是缓存残留导致的旧SHA关联问题，进入项目的「Admin」→「Advanced」选项卡：

  • 找到「Clear build cache」按钮，点击清除缓存
  • 之后再次触发Stable版本的手动构建

按这个流程操作下来，基本就能解决Stable版本关联无效SHA的问题了。

内容的提问来源于stack exchange，提问作者mr.adam