[git-push webhooks] Add integration with readthedocs

[Alvaro Uria]

Git repositories can have a webhook configured. Optionally, a secret can be stored so the POST request can have a special header passed with a hash calculated from the mentioned secret value.

This approach does not work for generic webhooks APIs such as the readthedocs one [1].

When a push notification is received, launchpad should be able to run a similar command to:

curl -X POST -d 'branch=stable' -d "token=$TOKEN" https://readthedocs.org/api/v2/webhook/<project-name>/<id>/

As a wishlist, the webhook should be configurable for specific branches (e.g. the "stable" branch instead of any branch or the "master" one itself).

1. https://docs.readthedocs.io/en/stable/webhooks.html

[Colin Watson (cjwatson)]

I looked at this recently. I think a preferable option would be to add support to readthedocs to support Launchpad's webhook format, since it already has customized support for several other hosting sites, and this would allow better handling on their side anyway. https://paste.ubuntu.com/p/wbJfBp9Gh9/ is a start at this, but there are probably a few other bits I've missed, and it needs tests.

[Colin Watson (cjwatson)]

The readthedocs maintainers have unfortunately nacked the idea of supporting Launchpad's webhook format in https://github.com/readthedocs/readthedocs.org/issues/8137. I'm not thrilled about that, but there doesn't seem to be much we can do about it.

So, what else is possible? We should probably expect to run into similar problems with other services, so maybe we need to consider some kind of custom webhook payload facility? For example, if you could specify something like a Jinja template into which you could substitute variables from the normal payload, then you could say something like this (rough sketch):

  {"branches": "{{ref_changes.keys()}}", "token": "fixed token you got from readthedocs"}

Of course Jinja may not be quite the right tool to use for generating JSON, but hopefully you get the idea. And we might need to cope with different branch naming conventions (e.g. whether the leading `refs/heads/` is supposed to be present or not).

[Juan Luis Cano (astrojuanlu)]

Hi all, Juan Luis from Read the Docs here. We are exploring possible workarounds and ways forward so that Launchpad projects work on RTD. Hopefully, no changes should be needed in Launchpad (more details in our GitHub issue tracker).