blob: d936d4ef98b54d7fd074923d86936af3243dd1fc [file] [log] [blame]
James E. Blaircdd00072012-06-08 19:17:28 -07001:title: Launchers
2
3Launchers
4=========
5
6Zuul has a modular architecture for launching jobs. Currently only
7Jenkins is supported, but it should be fairly easy to add a module to
8support other systems. Zuul makes very few assumptions about the
9interface to a launcher -- if it can trigger jobs, cancel them, and
10receive success or failure reports, it should be able to be used with
11Zuul. Patches to this effect are welcome.
12
13Jenkins
14-------
15
16Zuul works with Jenkins using the Jenkins API and the notification
17module. It uses the Jenkins API to trigger jobs, passing in
18parameters indicating what should be tested. It recieves
19notifications on job completion via the notification API (so jobs must
20be conifigured to notify Zuul).
21
22Jenkins Configuration
23~~~~~~~~~~~~~~~~~~~~~
24
25Zuul will need access to a Jenkins user. Create a user in Jenkins,
26and then visit the configuration page for the user:
27
28 https://jenkins.example.com/user/USERNAME/configure
29
30And click **Show API Token** to retrieve the API token for that user.
31You will need this later when configuring Zuul. Make sure that this
32user has appropriate permission to build any jobs that you want Zuul
33to trigger.
34
35Make sure the notification plugin is installed. Visit the plugin
36manager on your jenkins:
37
38 https://jenkins.example.com/pluginManager/
39
40And install **Jenkins Notification plugin**. The homepage for the
41plugin is at:
42
43 https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin
44
45Jenkins Job Configuration
46~~~~~~~~~~~~~~~~~~~~~~~~~
47
48For each job that you want Zuul to trigger, you will need to add a
49notification endpoint for the job on that job's configuration page.
50Click **Add Endpoint** and enter the following values:
51
52**Protocol**
53 ``HTTP``
54**URL**
55 ``http://127.0.0.1:8001/jenkins_endpoint``
56
57If you are running Zuul on a different server than Jenkins, enter the
58appropriate URL. Note that Zuul itself has no access controls, so
59ensure that only Jenkins is permitted to access that URL.
60
61Zuul will pass some parameters to Jenkins for every job it launches.
62Check **This build is parameterized**, and add the following fields
63with the type **String Parameter**:
64
65**UUID**
66 Zuul provided key to link builds with Gerrit events
67**GERRIT_PROJECT**
68 Zuul provided project name
69**GERRIT_BRANCH**
70 Zuul provided branch name
71**GERRIT_CHANGES**
72 Zuul provided list of dependent changes to merge
73
74You may find it useful to use the ``GERRIT_*`` variables in your job.
75In particular, ``GERRIT_CHANGES`` indicates the change or changes that
76should be tested. If Zuul has decided that more than one change
77should be merged and tested together, they will all be listed in
78``GERRIT_CHANGES``. The format for the description of one change is::
79
80 project:branch:refspec
81
82And multiple changes are separated by a carat ("^"). E.g.::
83
84 testproject:master:refs/changes/20/420/1^testproject:master:refs/changes/21/421/1"
85
86The OpenStack project uses the following script to update the
87repository in a workspace and merge appropriate changes:
88
89 https://github.com/openstack/openstack-ci-puppet/blob/master/modules/jenkins_slave/files/slave_scripts/gerrit-git-prep.sh
90
91Gerrit events that do not include a change (e.g., ref-updated events
92which are emitted after a git ref is updated (i.e., a commit is merged
93to master)) require a slightly different set of parameters:
94
95**UUID**
96 Zuul provided key to link builds with Gerrit events
97**GERRIT_PROJECT**
98 Zuul provided project name
99**GERRIT_REFNAME**
100 Zuul provided ref name
101**GERRIT_OLDREV**
102 Zuul provided old reference for ref-updated
103**GERRIT_NEWREV**
104 Zuul provided new reference for ref-updated
105