James E. Blair | 172c076 | 2012-10-02 15:35:54 -0700 | [diff] [blame] | 1 | .. _launchers: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 2 | :title: Launchers |
| 3 | |
| 4 | Launchers |
| 5 | ========= |
| 6 | |
| 7 | Zuul has a modular architecture for launching jobs. Currently only |
| 8 | Jenkins is supported, but it should be fairly easy to add a module to |
| 9 | support other systems. Zuul makes very few assumptions about the |
| 10 | interface to a launcher -- if it can trigger jobs, cancel them, and |
| 11 | receive success or failure reports, it should be able to be used with |
| 12 | Zuul. Patches to this effect are welcome. |
| 13 | |
| 14 | Jenkins |
| 15 | ------- |
| 16 | |
| 17 | Zuul works with Jenkins using the Jenkins API and the notification |
| 18 | module. It uses the Jenkins API to trigger jobs, passing in |
| 19 | parameters indicating what should be tested. It recieves |
| 20 | notifications on job completion via the notification API (so jobs must |
| 21 | be conifigured to notify Zuul). |
| 22 | |
| 23 | Jenkins Configuration |
| 24 | ~~~~~~~~~~~~~~~~~~~~~ |
| 25 | |
| 26 | Zuul will need access to a Jenkins user. Create a user in Jenkins, |
| 27 | and then visit the configuration page for the user: |
| 28 | |
| 29 | https://jenkins.example.com/user/USERNAME/configure |
| 30 | |
| 31 | And click **Show API Token** to retrieve the API token for that user. |
| 32 | You will need this later when configuring Zuul. Make sure that this |
| 33 | user has appropriate permission to build any jobs that you want Zuul |
| 34 | to trigger. |
| 35 | |
| 36 | Make sure the notification plugin is installed. Visit the plugin |
| 37 | manager on your jenkins: |
| 38 | |
| 39 | https://jenkins.example.com/pluginManager/ |
| 40 | |
| 41 | And install **Jenkins Notification plugin**. The homepage for the |
| 42 | plugin is at: |
| 43 | |
| 44 | https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin |
| 45 | |
| 46 | Jenkins Job Configuration |
| 47 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 48 | |
| 49 | For each job that you want Zuul to trigger, you will need to add a |
| 50 | notification endpoint for the job on that job's configuration page. |
| 51 | Click **Add Endpoint** and enter the following values: |
| 52 | |
| 53 | **Protocol** |
| 54 | ``HTTP`` |
| 55 | **URL** |
| 56 | ``http://127.0.0.1:8001/jenkins_endpoint`` |
| 57 | |
| 58 | If you are running Zuul on a different server than Jenkins, enter the |
| 59 | appropriate URL. Note that Zuul itself has no access controls, so |
| 60 | ensure that only Jenkins is permitted to access that URL. |
| 61 | |
| 62 | Zuul will pass some parameters to Jenkins for every job it launches. |
| 63 | Check **This build is parameterized**, and add the following fields |
| 64 | with the type **String Parameter**: |
| 65 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 66 | **ZUUL_UUID** |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 67 | Zuul provided key to link builds with Gerrit events |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 68 | **ZUUL_REF** |
| 69 | Zuul provided ref that includes commit(s) to build |
| 70 | **ZUUL_COMMIT** |
| 71 | The commit SHA1 at the head of ZUUL_REF |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 72 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 73 | Those are the only required parameters. The UUID is needed for Zuul |
| 74 | to keep track of the build, and the REF and COMMIT parameters are for |
| 75 | use in preparing the git repo for the build. The following parameters |
| 76 | will be sent for all builds, but are not required so you do not need |
| 77 | to configure Jenkins to accept them if you do not plan on using them: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 78 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 79 | **ZUUL_PROJECT** |
| 80 | The project that triggered this build |
| 81 | **ZUUL_PIPELINE** |
| 82 | The Zuul pipeline that is building this job |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 83 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 84 | The following parameters are optional and will only be provided for |
| 85 | builds associated with changes (i.e., in response to patchset-created |
| 86 | or comment-added events): |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 87 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 88 | **ZUUL_BRANCH** |
| 89 | The target branch for the change that triggered this build |
| 90 | **ZUUL_CHANGE** |
| 91 | The Gerrit change ID for the change that triggered this build |
| 92 | **ZUUL_CHANGE_IDS** |
| 93 | All of the Gerrit change IDs that are included in this build (useful |
| 94 | when the DependentPipelineManager combines changes for testing) |
| 95 | **ZUUL_PATCHSET** |
| 96 | The Gerrit patchset number for the change that triggered this build |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 97 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 98 | The following parameters are optional and will only be provided for |
| 99 | post-merge (ref-updated) builds: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 100 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 101 | **ZUUL_OLDREV** |
| 102 | The SHA1 of the old revision at this ref (recall the ref name is |
| 103 | in ZUUL_REF) |
| 104 | **ZUUL_NEWREV** |
| 105 | The SHA1 of the new revision at this ref (recall the ref name is |
| 106 | in ZUUL_REF) |
| 107 | **ZUUL_SHORT_OLDREV** |
| 108 | The shortened (7 character) SHA1 of the old revision |
| 109 | **ZUUL_SHORT_NEWREV** |
| 110 | The shortened (7 character) SHA1 of the new revision |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 111 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 112 | In order to test the correct build, configure the Jenkins Git SCM |
| 113 | plugin as follows:: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 114 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 115 | Source Code Management: |
| 116 | Git |
| 117 | Repositories: |
| 118 | Repository URL: <your Gerrit or Zuul repository URL> |
| 119 | Advanced: |
| 120 | Refspec: ${ZUUL_REF} |
| 121 | Branches to build: |
| 122 | Branch Specifier: ${ZUUL_COMMIT} |
| 123 | Advanced: |
| 124 | Clean after checkout: True |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 125 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame^] | 126 | That should be sufficient for a job that only builds a single project. |
| 127 | If you have multiple interrelated projects (i.e., they share a Zuul |
| 128 | Change Queue) that are built together, you may be able to configure |
| 129 | the Git plugin to prepare them, or you may chose to use a shell script |
| 130 | instead. The OpenStack project uses the following script to prepare |
| 131 | the workspace for its integration testing: |
| 132 | |
| 133 | https://github.com/openstack-ci/devstack-gate/blob/master/devstack-vm-gate-wrap.sh |