Open Stack

Hello,

tl;dr : any projects using the "docs-on-readthedocs" job template
to trigger a build of their documentation in readthedocs needs to:

 1) add the "openstackci" user as a maintainer of the RTD project
 2) generate a webhook integration URL for the project via RTD
 3) provide the unique webhook ID value in the "rtd_webhook_id" project
    variable

See

 https://docs.openstack.org/infra/openstack-zuul-jobs/project-templates.html#project_template-docs-on-readthedocs

--

readthedocs has recently updated their API for triggering a
documentation build.  In the old API, anyone could POST to a known URL
for the project and it would trigger a build.  This end-point has
stopped responding and we now need to use an authenticated webhook to
trigger documentation builds.

Since this is only done in the post and release pipelines, projects
probably haven't had great feedback that current methods are failing
and this may be a surprise.  To check your publishing, you can go to
the zuul builds page [1] and filter by your project and the "post"
pipeline to find recent runs.

There is now some setup required which can only be undertaken by a
current maintainer of the RTD project.

In short; add the "openstackci" user as a maintainer, add a "generic
webhook" integration to the project, find the last bit of the URL from
that and put it in the project variable "rtd_webhook_id".

Luckily OpenStack infra keeps a team of highly skilled digital artists
on retainer and they have produced a handy visual guide available at

  https://imgur.com/a/Pp4LH31

Once the RTD project is setup, you must provide the webhook ID value
in your project variables.  This will look something like:

 - project:
    templates:
      - docs-on-readthedocs
      - publish-to-pypi
    vars:
      rtd_webhook_id: '12345'
    check:
      jobs:
      ...

For actual examples; see pbrx [2] which keeps its config in tree, or
gerrit-dash-creator which has its configuration in project-config [3].

Happy to help if anyone is having issues, via mail or #openstack-infra

Thanks!

-i

p.s. You don't *have* to use the jobs from the docs-on-readthedocs
templates and hence add infra as a maintainer; you can setup your own
credentials with zuul secrets in tree and write your playbooks and
jobs to use the generic role [4].  We're always happy to discuss any
concerns.

[1] https://zuul.openstack.org/builds.html
[2] https://git.openstack.org/cgit/openstack/pbrx/tree/.zuul.yaml#n17
[3] https://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul.d/projects.yaml
[4] https://zuul-ci.org/docs/zuul-jobs/roles.html#role-trigger-readthedocs