Accessing builds or versions for a Github PR that has not triggered at least one build

[dmick]

We have 'build on github pull requests' enabled for our project, and we can retrigger failed builds by POSTing to /api/v3/projects//versions/<pr#>/builds/, and also those builds show up in the listing of builds from /api/v3/projects//builds, with "version" set to the PR number, but how does one create a build for a Github PR when it has failed to build the first one (i.e. if there are no builds, how do we start one for a PR)?

[humitos]

What's the error you are receiving when you POST to /api/v3/projects//versions/<pr#>/builds/ for a PR with a failing build?

Also, can you share the URL of your PR version on Read the Docs you are testing?

[dmick]

The error was No version matches the given query. At the time, the URL was /api/v3/projects/ceph/versions/62403/builds; since then we managed to trigger a build so it may not be in the same condition anymore.

The confusion was "what if there is no version/build available, how do we trigger it with the API" because that first build usually happens from the GH PR webhook

[humitos]

The version (on Read the Docs) pointing to the GH PR is created when the GH PR is opened, or a few seconds later --considering some potential delay. Once the version is created on Read the Docs, it's possible to trigger a build on that version using the API (https://docs.readthedocs.com/platform/stable/api/v3.html#build-triggering)

I just tested with my test-builds and it worked fine:

$ curl -X POST -H "Authorization: Token <mytoken>" https://readthedocs.org/api/v3/projects/test-builds/versions/2119/builds/

and this build was triggered: https://app.readthedocs.org/projects/test-builds/builds/28921494/

[dmick]

Yes, I understand. The issue was that a PR was opened, but apparently the version was never created; I don't know if the webhook was lost or what, but the PR was opened and the build never happened, so retriggering the build was not possible.

So again, what I'm asking is, is there a way with the API to cause the version to be known (perhaps to trigger that first build).

[humitos]

The issue was that a PR was opened, but apparently the version was never created; I don't know if the webhook was lost or what, but the PR was opened and the build never happened

If that's the case, let's focus on fixing that. Take a look at this section https://docs.readthedocs.com/platform/stable/guides/pull-requests.html#troubleshooting

Also, are you using the OAuth GitHub application, or the new GitHub App we deployed a few weeks ago? https://about.readthedocs.com/blog/2025/06/announcing-our-github-app-beta/

[dmick]

Many, many pull requests have worked fine in the past and continue to work now. This was an unusual incident.

We haven't yet investigated the GitHub App.

It sounds like the answer is going to be "the initial version creation must happen on the PR webhook". That's fine; I just wanted to make sure I wasn't missing anything that could help to compensate for errors in this unreliable (not a value judgement, just not designed to be reliable) messaging interface.

[humitos]

It sounds like the answer is going to be "the initial version creation must happen on the PR webhook".

Yes. The webhook is the one that creates the version object on Read the Docs.

[stsewd]

Pushing a new commit or closing and opening the pr should create the version on RTD if there was a problem

[dmick]

Got it. I'm only assuming that something went wrong with the webhook initially. But now I know.