This is a lightweight documentation intended to get operators started with setting up the Zuul3 service. For more insight on what Zuul3 can do, please refer to its upstream documentation.
The zuul(V3) service is installed with rh-python35 software collections:
- The configuration is located in /etc/zuul3
- The logs are written to /var/log/zuul3
- The services are prefixed with rh-python35-
A convenient wrapper for the command line is installed in /usr/bin/zuul3.
By default, no merger are being deployed because the executor service can perform merge task. However, a merger can also be deployed to speed up start time when there are many projects defined.
Configure an external gerrit (use Software Factory as a Third-Party CI)¶
Refer to the Third-Party-CI Quick Start guide
Create a GitHub app¶
To create a GitHub app on my-org follow this github documentation:
- Go to https://github.com/organizations/my-org/settings/apps/new
- Set GitHub App name to “my-org-zuul”
- Set Homepage URL to “https://fqdn”
- Set Setup URL to “https://fqdn/docs/project_config/zuul3_user.html#adding-a-project-to-the-zuulv3-service”
- Set Webhook URL to “https://fqdn/zuul3/connection/github.com/payload”
- Create a Webhook secret
- Set permissions:
- Commit statuses: Read & Write
- Issues: Read & Write
- Pull requests: Read & Write
- Repository contents: Read & Write (write to let zuul merge change)
- Set events subscription:
- Issue comment
- Pull request
- Pull request review
- Pull request review comment
- Commit comment
- Set Where can this GitHub App be installed to “Any account”
- Create the App
- In the ‘General’ tab generate a Private key for your application
Configure the Github connection in sfconfig.yaml, add to the github_connections:
- name: "github.com" webhook_token: uuid # The token used in app creation app_id: 42 # Can be found under the Public Link on the right hand side labeled ID. app_key: | # In Github this is known as Private key and must be collected when generated -----BEGIN RSA PRIVATE KEY----- KEY CONTENT HERE -----END RSA PRIVATE KEY-----
Then run sfconfig to apply the configuration. And finally verify in the ‘Advanced’ tab that the Ping payload works (green tick and 200 response). Click “Redeliver” if needed.
It’s recommended to use a GitHub app instead of manual webhook. When using manual webhook, set the api_token instead of the app_id and app_key. Manual webhook documentation is still TBD…
Check out the Zuul GitHub App user documentation to start using the application.
More information about the Zuul’s Github driver can be found in the Zuul Github driver manual.
The zuul-scheduler can automatically import all the jobs defined in the openstack-infra/zuul-jobs repository. Use this command line to enable its usage:
Troubleshooting non starting jobs¶
- First check that the project is defined in /etc/opt/rh/rh-python35/zuul/main.yaml
- Then check in scheduler.log that it correctly requested a node and submitted a job to the executor
- When zuul reports PRE_FAILURE or POST_FAILURE, then the executor’s debugging needs to be turned on
- Finally passing all loggers’ level to DEBUG in /etc/opt/rh/rh-python35/zuul/scheduler-logging.yaml then restarting the service rh-python35-zuul-scheduler might help to debug.
Troubleshooting the executor¶
First you need to enable the executor’s keepjob option so that ansible logs are available on dist:
/opt/rh/rh-python35/root/bin/zuul-executor -c /etc/zuul3/zuul.conf keep
Then next job execution will be available in /tmp/systemd-private--rh-python35-zuul-executor.service-/tmp/
In particular, the work/ansible/job-logs.txt usually tells why a job failed.
When done with debugging, deactivate the keepjob option by running:
/opt/rh/rh-python35/root/bin/zuul-executor -c /etc/opt/rh/rh-python35/zuul/zuul.conf nokeep