You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.0 KiB


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.


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:

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:




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 provided key to link builds with Gerrit events


Zuul provided ref that includes commit(s) to build


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.


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:


The project that triggered this build


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):


The target branch for the change that triggered this build


The Gerrit change ID for the change that triggered this build


All of the Gerrit change IDs that are included in this build (useful when the DependentPipelineManager combines changes for testing)


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:


The SHA1 of the old revision at this ref (recall the ref name is in ZUUL_REF)


The SHA1 of the new revision at this ref (recall the ref name is in ZUUL_REF)


The shortened (7 character) SHA1 of the old revision


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:
      Repository URL:  <your Gerrit or Zuul repository URL>
          Refspec: ${ZUUL_REF}
    Branches to build:
      Branch Specifier: ${ZUUL_COMMIT}
      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: