[openstack-dev] [all][docs] ACTION REQUIRED for projects using readthedocs
iwienand at redhat.com
Fri Aug 3 04:20:40 UTC 2018
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
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  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
Once the RTD project is setup, you must provide the webhook ID value
in your project variables. This will look something like:
For actual examples; see pbrx  which keeps its config in tree, or
gerrit-dash-creator which has its configuration in project-config .
Happy to help if anyone is having issues, via mail or #openstack-infra
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 . We're always happy to discuss any
More information about the OpenStack-dev