如何让RTD识别未触发初始构建的Github PR并触发构建？

问题背景 #

我们为Ceph项目启用了Read the Docs（RTD）的Pull Requests Builds，日常运行正常；同时配置了GitHub Workflow，允许开发者通过PR评论触发短语重新构建——只要RTD已“知晓”该PR，这个功能就能正常工作。

但如果因网络或Webhook故障，RTD未收到PR打开时的初始触发payload，直接调用现有重构建API会返回{"detail":"No Version matches the given query"}。我们尝试过通过PR编号查询版本API，也无法找到对应记录，需要明确如何手动让RTD识别该PR并触发构建。

解决方案 #

当RTD未识别目标PR时，需要先手动创建对应PR的版本记录，再触发构建，具体步骤如下：

1. 创建PR对应的RTD版本 #

调用RTD版本创建API，提交PR的关键信息：

curl -X POST "https://readthedocs.org/api/v3/projects/ceph/versions/" \
  -H "Authorization: Token YOUR_RTD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "PR-62403",
    "verbose_name": "PR #62403",
    "type": "external",
    "identifier": "refs/pull/62403/head",
    "active": true,
    "privacy_level": "public"
  }'

参数说明：

• slug：版本的唯一标识，建议采用PR-{PR编号}格式，便于识别
• verbose_name：版本的显示名称，清晰标注PR编号即可
• type：固定为external，表示这是外部PR对应的版本
• identifier：对应GitHub PR的代码引用，格式为refs/pull/{PR编号}/head
• active：设为true以启用该版本
• privacy_level：与项目隐私设置保持一致，这里使用public

2. 触发该版本的构建 #

版本创建成功后，即可使用原有的构建触发API（此时版本已存在，不会再返回“无匹配版本”错误）：

curl -X POST "https://readthedocs.org/api/v3/projects/ceph/versions/PR-62403/builds/" \
  -H "Authorization: Token YOUR_RTD_API_TOKEN" \
  -H "Content-Type: application/json"

如果创建版本时API返回了版本ID，也可以用版本ID替换slug进行调用：

curl -X POST "https://readthedocs.org/api/v3/projects/ceph/versions/{VERSION_ID}/builds/" \
  -H "Authorization: Token YOUR_RTD_API_TOKEN" \
  -H "Content-Type: application/json"

优化建议 #

可以将上述两步整合到现有GitHub Workflow中，先调用GET /api/v3/projects/ceph/versions/?slug=PR-{PR编号}检查版本是否存在：

• 若存在，直接触发构建
• 若不存在，先创建版本再触发构建

示例对比 #

已识别PR的重构建（成功） #

curl -X POST "https://readthedocs.org/api/v3/projects/ceph/versions/64571/builds/" -H "Authorization: Token ***" -H "Content-Type: application/json"

返回成功响应：

{"build":{"_links":{"_self":"https://app.readthedocs.org/api/v3/projects/ceph/builds/28894941/","notifications":"https://app.readthedocs.org/api/v3/projects/ceph/builds/28894941/notifications/","project":"https://app.readthedocs.org/api/v3/projects/ceph/","version":"https://app.readthedocs.org/api/v3/projects/ceph/versions/64571/"},"commit":"204aa81bcb7ac0041e902ecb717eed24c89b7941","created":"2025-07-17T22:46:41.028135Z","duration":null,"error":"","finished":null,"id":28894941,"project":"ceph","state":{"code":"triggered","name":"Triggered"},"success":null,"urls":{"build":"https://app.readthedocs.org/projects/ceph/builds/28894941/","project":"https://app.readthedocs.org/projects/ceph/","version":"https://app.readthedocs.org/dashboard/ceph/version/64571/edit/"},"version":"64571"},"project":{"_links":{"_self":"https://app.readthedocs.org/api/v3/projects/ceph/","builds":"https://app.readthedocs.org/api/v3/projects/ceph/builds/","environmentvariables":"https://app.readthedocs.org/api/v3/projects/ceph/environmentvariables/","notifications":"https://app.readthedocs.org/api/v3/projects/ceph/notifications/","redirects":"https://app.readthedocs.org/api/v3/projects/ceph/redirects/","subprojects":"https://app.readthedocs.org/api/v3/projects/ceph/subprojects/","superproject":"https://app.readthedocs.org/api/v3/projects/ceph/superproject/","sync_versions":"https://app.readthedocs.org/api/v3/projects/ceph/sync-versions/","translations":"https://app.readthedocs.org/api/v3/projects/ceph/translations/","versions":"https://app.readthedocs.org/api/v3/projects/ceph/versions/"},"created":"2020-04-07T05:56:43.794056Z","default_branch":"main","default_version":"latest","external_builds_privacy_level":"public","homepage":"https://ceph.io","id":591015,"language":{"code":"en","name":"English"},"modified":"2025-07-11T18:29:44.780898Z","name":"ceph","privacy_level":"public","programming_language":{"code":"cpp","name":"C++"},"repository":{"type":"git","url":"https://github.com/ceph/ceph.git"},"single_version":false,"slug":"ceph","subproject_of":null,"tags":[],"translation_of":null,"urls":{"builds":"https://app.readthedocs.org/projects/ceph/builds/","documentation":"https://docs.ceph.com/en/latest/","downloads":null,"home":"https://app.readthedocs.org/projects/ceph/","versions":"https://app.readthedocs.org/projects/ceph/versions/"},"users":[{"username":"dmick"},{"username":"zdover23"},{"username":"tchaikov"},{"username":"jdurgin"},{"username":"neha-ojha"},{"username":"djgalloway"},{"username":"batrick"},{"username":"zmc"},{"username":"ljflores"}],"versioning_scheme":"multiple_versions_with_translations"},"triggered":true,"version":{"_links":{"_self":"https://app.readthedocs.org/api/v3/projects/ceph/versions/64571/","builds":"https://app.readthedocs.org/api/v3/projects/ceph/versions/64571/builds/","project":"https://app.readthedocs.org/api/v3/projects/ceph/"},"active":true,"aliases":[],"built":false,"downloads":{},"hidden":false,"id":21574255,"identifier":"204aa81bcb7ac0041e902ecb717eed24c89b7941","privacy_level":"public","ref":null,"slug":"64571","type":"external","urls":{"dashboard":{"edit":"https://app.readthedocs.org/dashboard/ceph/version/64571/edit/"},"documentation":"https://ceph--64571.org.readthedocs.build/en/64571/","vcs":"https://github.com/ceph/ceph/pull/64571"},"verbose_name":"64571"}}

未识别PR的重构建（失败） #

curl -X POST "https://readthedocs.org/api/v3/projects/ceph/versions/62403/builds/" -H "Authorization: Token ***" -H "Content-Type: application/json"

返回错误：

{"detail":"No Version matches the given query."}

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