ReadTheDocs automatic builds are unusable with Codeberg (and Gitea in general)

Install/Maintain/Configure
1

ReadTheDocs (RTD) is a well-known documentation hosting service, offering free builds and hosting for Sphinx and MkDocs based documentation. It’s quite popular in the Python world but not limited to it. RTD can do automatic builds of documentation in a CI/CD fashion - however this is based on a webhook that is not apparently working for the combination of RTD and Gitea.

The issue was described here Possibility to configure name of the "secret" field in POST webhook · Issue #7487 · go-gitea/gitea · GitHub and then it got closed because of some changes in the Gitea webhook implementation that are a bit obscure for me.

If I understand correctly, both RTD and Gitea have a hardcoded name for the “secret” variable and they’re not compatible, but I may be wrong.

As it stands, the only possibility to build documentation on RTD from a Gitea repository is to manually launch a build from the RTD dashboard.

This is the specific webhook configuration page, showing the “Token” parameter (the shown value has been deleted since the screenshot was taken).

immagine

Any suggestions? My repositories are hosted on Codeberg.

2

That field has been deprecated since Gitea v1.12 (IIRC), and fully removed in 1.15 (which codeberg will soon upgrade to once it is fully released), as it had possibility of leaking that shared secret.

Support for parsing Gitea webhooks will need to be added to RTD, as they have already for other services (GitHub, GitLab, and BitBucket)

1 Like
3

Thanks to the RTD developers I found that the issue is only in the UI and the existing features are enough for everything to work properly: just configure a GitHub webhook and feed it to Gitea with the URL and nothing else.

Further details here: Add Gitea as VCS provider · Issue #8364 · readthedocs/readthedocs.org · GitHub

Of course a friendly UI would be great but at least we know Read the Docs works well with any Gitea repository.

1 Like
4

The detailed instructions are now included in the official documentation of Read the Docs.