blob: eb8cd10efc8c9da911fca3fe0daa2c77cc78e0fc [file] [log] [blame]
James E. Blair172c0762012-10-02 15:35:54 -07001.. _launchers:
James E. Blaircdd00072012-06-08 19:17:28 -07002:title: Launchers
3
4Launchers
5=========
6
7Zuul has a modular architecture for launching jobs. Currently only
8Jenkins is supported, but it should be fairly easy to add a module to
9support other systems. Zuul makes very few assumptions about the
10interface to a launcher -- if it can trigger jobs, cancel them, and
11receive success or failure reports, it should be able to be used with
12Zuul. Patches to this effect are welcome.
13
14Jenkins
15-------
16
17Zuul works with Jenkins using the Jenkins API and the notification
18module. It uses the Jenkins API to trigger jobs, passing in
19parameters indicating what should be tested. It recieves
20notifications on job completion via the notification API (so jobs must
21be conifigured to notify Zuul).
22
23Jenkins Configuration
24~~~~~~~~~~~~~~~~~~~~~
25
26Zuul will need access to a Jenkins user. Create a user in Jenkins,
27and then visit the configuration page for the user:
28
29 https://jenkins.example.com/user/USERNAME/configure
30
31And click **Show API Token** to retrieve the API token for that user.
32You will need this later when configuring Zuul. Make sure that this
33user has appropriate permission to build any jobs that you want Zuul
34to trigger.
35
36Make sure the notification plugin is installed. Visit the plugin
37manager on your jenkins:
38
39 https://jenkins.example.com/pluginManager/
40
41And install **Jenkins Notification plugin**. The homepage for the
42plugin is at:
43
44 https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin
45
46Jenkins Job Configuration
47~~~~~~~~~~~~~~~~~~~~~~~~~
48
49For each job that you want Zuul to trigger, you will need to add a
50notification endpoint for the job on that job's configuration page.
51Click **Add Endpoint** and enter the following values:
52
53**Protocol**
54 ``HTTP``
55**URL**
56 ``http://127.0.0.1:8001/jenkins_endpoint``
57
58If you are running Zuul on a different server than Jenkins, enter the
59appropriate URL. Note that Zuul itself has no access controls, so
60ensure that only Jenkins is permitted to access that URL.
61
62Zuul will pass some parameters to Jenkins for every job it launches.
63Check **This build is parameterized**, and add the following fields
64with the type **String Parameter**:
65
James E. Blair81515ad2012-10-01 18:29:08 -070066**ZUUL_UUID**
James E. Blaircdd00072012-06-08 19:17:28 -070067 Zuul provided key to link builds with Gerrit events
James E. Blair81515ad2012-10-01 18:29:08 -070068**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. Blaircdd00072012-06-08 19:17:28 -070072
James E. Blair81515ad2012-10-01 18:29:08 -070073Those are the only required parameters. The UUID is needed for Zuul
74to keep track of the build, and the REF and COMMIT parameters are for
75use in preparing the git repo for the build. The following parameters
76will be sent for all builds, but are not required so you do not need
77to configure Jenkins to accept them if you do not plan on using them:
James E. Blaircdd00072012-06-08 19:17:28 -070078
James E. Blair81515ad2012-10-01 18:29:08 -070079**ZUUL_PROJECT**
80 The project that triggered this build
81**ZUUL_PIPELINE**
82 The Zuul pipeline that is building this job
James E. Blaircdd00072012-06-08 19:17:28 -070083
James E. Blair81515ad2012-10-01 18:29:08 -070084The following parameters are optional and will only be provided for
85builds associated with changes (i.e., in response to patchset-created
86or comment-added events):
James E. Blaircdd00072012-06-08 19:17:28 -070087
James E. Blair81515ad2012-10-01 18:29:08 -070088**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. Blaircdd00072012-06-08 19:17:28 -070097
James E. Blair81515ad2012-10-01 18:29:08 -070098The following parameters are optional and will only be provided for
99post-merge (ref-updated) builds:
James E. Blaircdd00072012-06-08 19:17:28 -0700100
James E. Blair81515ad2012-10-01 18:29:08 -0700101**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. Blaircdd00072012-06-08 19:17:28 -0700111
James E. Blair81515ad2012-10-01 18:29:08 -0700112In order to test the correct build, configure the Jenkins Git SCM
113plugin as follows::
James E. Blaircdd00072012-06-08 19:17:28 -0700114
James E. Blair81515ad2012-10-01 18:29:08 -0700115 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. Blaircdd00072012-06-08 19:17:28 -0700125
James E. Blair81515ad2012-10-01 18:29:08 -0700126That should be sufficient for a job that only builds a single project.
127If you have multiple interrelated projects (i.e., they share a Zuul
128Change Queue) that are built together, you may be able to configure
129the Git plugin to prepare them, or you may chose to use a shell script
130instead. The OpenStack project uses the following script to prepare
131the workspace for its integration testing:
132
133 https://github.com/openstack-ci/devstack-gate/blob/master/devstack-vm-gate-wrap.sh