This document the required permissions of the Zuul Jenkins user. Change-Id: Id977e3813f943b032c7628d8cdc663b3bdbb688d Reviewed-on: https://review.openstack.org/16528 Reviewed-by: Jeremy Stanley <fungi@yuggoth.org> Approved: Clark Boylan <clark.boylan@gmail.com> Reviewed-by: Clark Boylan <clark.boylan@gmail.com> Tested-by: Jenkins
5.0 KiB
Launchers
Zuul has a modular architecture for launching jobs. Currently only Jenkins is supported, but it should be fairly easy to add a module to support other systems. Zuul makes very few assumptions about the interface to a launcher -- if it can trigger jobs, cancel them, and receive success or failure reports, it should be able to be used with Zuul. Patches to this effect are welcome.
Jenkins
Zuul works with Jenkins using the Jenkins API and the notification module. It uses the Jenkins API to trigger jobs, passing in parameters indicating what should be tested. It recieves notifications on job completion via the notification API (so jobs must be conifigured to notify Zuul).
Jenkins Configuration
Zuul will need access to a Jenkins user. Create a user in Jenkins, and then visit the configuration page for the user:
And click Show API Token to retrieve the API token
for that user. You will need this later when configuring Zuul.
Appropriate user permissions must be set under the Jenkins security
matrix: under the Global
group of permissions, check
Read
, then under the Job
group of permissions,
check Read
and Build
. Finally, under
Run
check Update
. If using a per project
matrix, make sure the user permissions are properly set for any jobs
that you want Zuul to trigger.
Make sure the notification plugin is installed. Visit the plugin manager on your jenkins:
And install Jenkins Notification plugin. The homepage for the plugin is at:
https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin
Jenkins Job Configuration
For each job that you want Zuul to trigger, you will need to add a notification endpoint for the job on that job's configuration page. Click Add Endpoint and enter the following values:
- Protocol
-
HTTP
- URL
-
http://127.0.0.1:8001/jenkins_endpoint
If you are running Zuul on a different server than Jenkins, enter the appropriate URL. Note that Zuul itself has no access controls, so ensure that only Jenkins is permitted to access that URL.
Zuul will pass some parameters to Jenkins for every job it launches. Check This build is parameterized, and add the following fields with the type String Parameter:
- ZUUL_UUID
-
Zuul provided key to link builds with Gerrit events
- ZUUL_REF
-
Zuul provided ref that includes commit(s) to build
- ZUUL_COMMIT
-
The commit SHA1 at the head of ZUUL_REF
Those are the only required parameters. The ZUUL_UUID is needed for Zuul to keep track of the build, and the ZUUL_REF and ZUUL_COMMIT parameters are for use in preparing the git repo for the build.
Note
The GERRIT_PROJECT and UUID parameters are deprecated respectively in favor of ZUUL_PROJECT and ZUUL_UUID.
The following parameters will be sent for all builds, but are not required so you do not need to configure Jenkins to accept them if you do not plan on using them:
- ZUUL_PROJECT
-
The project that triggered this build
- ZUUL_PIPELINE
-
The Zuul pipeline that is building this job
The following parameters are optional and will only be provided for builds associated with changes (i.e., in response to patchset-created or comment-added events):
- ZUUL_BRANCH
-
The target branch for the change that triggered this build
- ZUUL_CHANGE
-
The Gerrit change ID for the change that triggered this build
- ZUUL_CHANGE_IDS
-
All of the Gerrit change IDs that are included in this build (useful when the DependentPipelineManager combines changes for testing)
- ZUUL_PATCHSET
-
The Gerrit patchset number for the change that triggered this build
The following parameters are optional and will only be provided for post-merge (ref-updated) builds:
- ZUUL_OLDREV
-
The SHA1 of the old revision at this ref (recall the ref name is in ZUUL_REF)
- ZUUL_NEWREV
-
The SHA1 of the new revision at this ref (recall the ref name is in ZUUL_REF)
- ZUUL_SHORT_OLDREV
-
The shortened (7 character) SHA1 of the old revision
- ZUUL_SHORT_NEWREV
-
The shortened (7 character) SHA1 of the new revision
In order to test the correct build, configure the Jenkins Git SCM plugin as follows:
Source Code Management:
Git
Repositories:
Repository URL: <your Gerrit or Zuul repository URL>
Advanced:
Refspec: ${ZUUL_REF}
Branches to build:
Branch Specifier: ${ZUUL_COMMIT}
Advanced:
Clean after checkout: True
That should be sufficient for a job that only builds a single project. If you have multiple interrelated projects (i.e., they share a Zuul Change Queue) that are built together, you may be able to configure the Git plugin to prepare them, or you may chose to use a shell script instead. The OpenStack project uses the following script to prepare the workspace for its integration testing:
https://github.com/openstack-ci/devstack-gate/blob/master/devstack-vm-gate-wrap.sh