On 2022-08-22 16:02:02 +0000 (+0000), Stone, Ronald wrote:

My company is researching Zuul for internal StarlingX docs builds.

That's awesome news! I hope you'll find it as invaluable as I do.

Can someone point out where we could find the config files for StarlingX docs on opendev.org? We're hoping to use them as a jumping off point for an internal implementation.

If you're talking about the starlingx/docs repo specifically, you'll see there's already a Zuul configuration file in it, though that's really just serving as an entry point for populating some project pipelines with jobs defined in other repos: https://opendev.org/starlingx/docs/src/branch/master/.zuul.yaml In particular, you're adding the openstack-tox-docs job to the check and gate pipelines along with the promote-stx-tox-docs-site job to the promote pipeline. It's also applying the stx-api-ref-jobs template which comes from here: https://opendev.org/starlingx/zuul-jobs/src/branch/master/zuul.d/project-tem... In that project-template entry you can see it's adding variants of build-openstack-api-ref and promote-stx-api-ref jobs to some pipelines as well. Some of these jobs are reused from OpenStack's definitions, as you can tell from their names, though the couple with "stx" in their names are defined in this trusted config repo because they need access to shared credentials in order to be able to write to the publication site: https://opendev.org/openstack/project-config/src/branch/master/zuul.d/starli... The reused OpenStack jobs on the other hand are being consumed from definitions here: https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/zuul.d/j... Zuul jobs also rely on inheritance, so you'll see for example the build-openstack-api-ref job inherits from the openstack-tox-docs job but overrides some specific variables and limits its scope to only triggering on master branches (because in OpenStack, APIs are versioned independently of the software which provides them). Then openstack-tox-docs in turn inherits from opendev-tox-docs with a variety of things overridden. You can find the opendev-tox-docs definition here: https://opendev.org/opendev/base-jobs/src/branch/master/zuul.d/jobs.yaml So I can already hear you asking, "how do I find and keep all these different sources/locations straight?" Zuul actually has a browseable configuration in its WebUI. You can see the project entry here shows all the jobs defined to run for various pipelines: https://zuul.opendev.org/t/openstack/project/opendev.org/starlingx/docs If you click on the build-openstack-api-ref entry, for example, it will take you to details about that job including the project and file which contains its definition along with a hyperlinked parent entry, which you can follow to get a similar view of the inherited job (continuing until you hit bedrock at the job named "base"). If you get stuck, all of those repositories can also be searched here: https://codesearch.opendev.org/ So anyway, that covers the basics of job definitions and how they're selected, but what do they actually run? For that you'll want to look for the "run" (often also "pre-run" and "post-run") playbooks. Those are paths to Ansible playbook files in the repositories where the job definitions reside. In the case of openstack-tox-docs for example, you'll see its run phase uses this playbook: https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/playbook... The roles in there are reusable sets of tasks (instructions basically), which can usually either be found in a "roles" top-level directory of the same project, or in a project expressly listed as providing additional roles in that job's definition or that of one of its ancestors. In this case you'll see Zuul's standard library (included by the "base" job definition) provides those revoke-sudo and tox roles, while build-pdf-docs comes from openstack/openstack-zuul-jobs where the job definition resides: https://opendev.org/zuul/zuul-jobs/src/branch/master/roles https://opendev.org/openstack/openstack-zuul-jobs/src/branch/master/roles As for what goes in roles and playbooks, well, that's the point at which you should consult the Ansible documentation, but I'm going to assume this is at least enough to get you started. -- Jeremy Stanley