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

Open
opened 3 weeks ago by steko · 9 comments
steko commented 3 weeks ago

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 https://github.com/go-gitea/gitea/issues/7487 and then it got closed because of some changes in the Gitea webhook implementation.

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 Codeberg repository is to manually launch a build from the RTD dashboard.

immagine

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

immagine

I don't know if this could be fixed specifically for Codeberg or if it's better resubmitted as an upstream issue, but as suggested on Mastodon it's better to open an issue so others can comment.

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 https://github.com/go-gitea/gitea/issues/7487 and then it got closed because of some changes in the Gitea webhook implementation. 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 Codeberg repository is to manually launch a build from the RTD dashboard. ![immagine](/attachments/2d6322b3-1a70-4181-ba49-52ff27adf6af) This is the specific webhook configuration page, showing the "Token" parameter (the shown value has been deleted since the screenshot was taken). ![immagine](/attachments/84cab224-00e0-4068-8fca-302d54430ed9) I don't know if this could be fixed specifically for Codeberg or if it's better resubmitted as an upstream issue, but as suggested on Mastodon it's better to open an issue so others can comment.
fnetX added the
question
gitea-related
labels 3 weeks ago
Poster
I posted the same summary here https://discourse.gitea.io/t/readthedocs-automatic-builds-are-unusable-with-codeberg-and-gitea-in-general/3533 on the Gitea forum.
6543 added
enhancement
and removed
question
labels 1 week ago
6543 commented 1 week ago
Collaborator

so you propose to add new webhook type "ReadTheDocs" to gitea i guess?

so you propose to add new webhook type "ReadTheDocs" to gitea i guess?
Collaborator

No, RTD should have Gitea support like it does for Github Bitbucket and Gitlab already. The secret field was removed for security reasons.

No, RTD should have Gitea support like it does for Github Bitbucket and Gitlab already. The secret field was removed for security reasons.
6543 removed the
enhancement
label 1 week ago
Collaborator

can someone reach out to them // open an issue there, if it should be addressed on ReadTheDocs side?

can someone reach out to them // open an issue there, if it should be addressed on ReadTheDocs side?
Poster

I think the best way forward is to open an issue with ReadTheDocs. I can open it but it would be very helpful if someone from the Gitea dev team and Codeberg sysadmin team could provide the necessary details if needed.

I think the best way forward is to open an issue with ReadTheDocs. I can open it but it would be very helpful if someone from the Gitea dev team and Codeberg sysadmin team could provide the necessary details if needed.
Poster
Here it is https://github.com/readthedocs/readthedocs.org/issues/8364

Hello folks! Juan Luis from Read the Docs here. Thanks @steko for opening the issue upstream, already left a comment there. From my limited understanding of webhooks and APIs it seems that Gitea is already using a quite standard header name, so this looks like we should fix things on our side. Can't give a specific timeline though, so if you happen to have a GitHub account, please keep your upvotes 👍 coming 😃 (no need to add a "me too" comment).

Hello folks! Juan Luis from Read the Docs here. Thanks @steko for opening the issue upstream, already left a comment there. From my limited understanding of webhooks and APIs it seems that Gitea is already using a quite standard header name, so this looks like we should fix things on our side. Can't give a specific timeline though, so if you happen to have a GitHub account, please keep your upvotes 👍 coming 😃 (no need to add a "me too" comment).
Poster

Well it was easy! Just configure a GitHub webhook and feed it to Gitea with the URL and nothing else. It works! 🚀

Further details here: https://github.com/readthedocs/readthedocs.org/issues/8364#issuecomment-887022857

Of course a friendly UI would be great but at least we know it works. Thank you @astrojuanlu for your analysis!

Well it was easy! Just configure a **GitHub** webhook and feed it to Gitea with the URL and nothing else. It works! 🚀 Further details here: https://github.com/readthedocs/readthedocs.org/issues/8364#issuecomment-887022857 Of course a friendly UI would be great but at least we know it works. Thank you @astrojuanlu for your analysis!
Collaborator

Of course a friendly UI would be great

On the side of ReadTheDocs or is there anything we can improve on Codeberg's / Gitea's side?

> Of course a friendly UI would be great On the side of ReadTheDocs or is there anything we can improve on Codeberg's / Gitea's side?
Sign in to join this conversation.
No Milestone
No Assignees
5 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.