blob: afe4cf6097f19f4d21738223c264a7f2accb145f [file] [log] [blame]
James E. Blaircdd00072012-06-08 19:17:28 -07001:title: Zuul
2
3Zuul
4====
5
6Configuration
7-------------
8
9Zuul has three configuration files:
10
11**zuul.conf**
James E. Blair1f4c2bb2013-04-26 08:40:46 -070012 Connection information for Gerrit and Gearman, locations of the
13 other config files
James E. Blaircdd00072012-06-08 19:17:28 -070014**layout.yaml**
Clark Boylan00635dc2012-09-19 14:03:08 -070015 Project and pipeline configuration -- what Zuul does
James E. Blaircdd00072012-06-08 19:17:28 -070016**logging.conf**
17 Python logging config
18
19Examples of each of the three files can be found in the etc/ directory
20of the source distribution.
21
James E. Blair6aea36d2012-12-17 13:03:24 -080022.. _zuulconf:
23
James E. Blaircdd00072012-06-08 19:17:28 -070024zuul.conf
25~~~~~~~~~
26
27Zuul will look for ``/etc/zuul/zuul.conf`` or ``~/zuul.conf`` to
28bootstrap its configuration. Alternately, you may specify ``-c
29/path/to/zuul.conf`` on the command line.
30
James E. Blair1f4c2bb2013-04-26 08:40:46 -070031Gerrit and Gearman connection information are each described in a
32section of zuul.conf. The location of the other two configuration
33files (as well as the location of the PID file when running Zuul as a
34server) are specified in a third section.
James E. Blaircdd00072012-06-08 19:17:28 -070035
Clark Boylan9b670902012-09-28 13:47:56 -070036The three sections of this config and their options are documented below.
37You can also find an example zuul.conf file in the git
38`repository
K Jonathan Harker97e457e2013-02-26 13:29:38 -080039<https://github.com/openstack-infra/zuul/blob/master/etc/zuul.conf-sample>`_
Clark Boylan9b670902012-09-28 13:47:56 -070040
James E. Blair1f4c2bb2013-04-26 08:40:46 -070041gearman
Clark Boylan9b670902012-09-28 13:47:56 -070042"""""""
43
44**server**
James E. Blair1f4c2bb2013-04-26 08:40:46 -070045 Hostname or IP address of the Gearman server.
46 ``server=gearman.example.com``
Clark Boylan9b670902012-09-28 13:47:56 -070047
James E. Blair1f4c2bb2013-04-26 08:40:46 -070048**port**
49 Port on which the Gearman server is listening
50 ``port=4730``
Clark Boylan9b670902012-09-28 13:47:56 -070051
James E. Blair77cc7b82013-07-15 13:22:37 -070052gearman_server
53""""""""""""""
54
55**start**
56 Whether to start the internal Gearman server (default: False).
57 ``start=true``
58
59**log_config**
60 Path to log config file for internal Gearman server.
61 ``log_config=/etc/zuul/gearman-logging.yaml``
62
Clark Boylan9b670902012-09-28 13:47:56 -070063gerrit
64""""""
65
66**server**
67 FQDN of Gerrit server.
68 ``server=review.example.com``
69
Antoine Musso27475012012-11-26 09:53:01 +010070**baseurl**
71 Optional: path to Gerrit web interface. Defaults to ``https://<value
72 of server>/``. ``baseurl=https://review.example.com/review_site/``
73
Clark Boylan9b670902012-09-28 13:47:56 -070074**user**
75 User name to use when logging into above server via ssh.
James E. Blair1f4c2bb2013-04-26 08:40:46 -070076 ``user=zuul``
Clark Boylan9b670902012-09-28 13:47:56 -070077
78**sshkey**
79 Path to SSH key to use when logging into above server.
James E. Blair1f4c2bb2013-04-26 08:40:46 -070080 ``sshkey=/home/zuul/.ssh/id_rsa``
Clark Boylan9b670902012-09-28 13:47:56 -070081
82zuul
83""""
84
85**layout_config**
86 Path to layout config file.
87 ``layout_config=/etc/zuul/layout.yaml``
88
89**log_config**
90 Path to log config file.
91 ``log_config=/etc/zuul/logging.yaml``
92
93**pidfile**
94 Path to PID lock file.
95 ``pidfile=/var/run/zuul/zuul.pid``
96
97**state_dir**
98 Path to directory that Zuul should save state to.
99 ``state_dir=/var/lib/zuul``
100
101**git_dir**
102 Directory that Zuul should clone local git repositories to.
103 ``git_dir=/var/lib/zuul/git``
104
Paul Belangerb67aba12013-05-13 19:22:14 -0400105**git_user_email**
106 Optional: Value to pass to `git config user.email`.
107 ``git_user_email=zuul@example.com``
108
109**git_user_name**
110 Optional: Value to pass to `git config user.name`.
111 ``git_user_name=zuul``
112
Clark Boylan9b670902012-09-28 13:47:56 -0700113**push_change_refs**
114 Boolean value (``true`` or ``false``) that determines if Zuul should
115 push change refs to the git origin server for the git repositories in
116 git_dir.
117 ``push_change_refs=true``
118
James E. Blair0ac6c012013-04-26 09:04:23 -0700119**report_times**
120 Boolean value (``true`` or ``false``) that determines if Zuul should
121 include elapsed times for each job in the textual report.
122 ``report_times=true``
123
Clark Boylan9b670902012-09-28 13:47:56 -0700124**status_url**
125 URL that will be posted in Zuul comments made to Gerrit changes when
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700126 starting jobs for a change.
127 ``status_url=https://zuul.example.com/status``
Clark Boylan9b670902012-09-28 13:47:56 -0700128
129**url_pattern**
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700130 If you are storing build logs external to the system that originally
131 ran jobs and wish to link to those logs when Zuul makes comments on
132 Gerrit changes for completed jobs this setting configures what the
133 URLs for those links should be.
Clark Boylan9b670902012-09-28 13:47:56 -0700134 ``http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}``
135
James E. Blair8fef52b2013-08-17 17:32:50 -0700136**job_name_in_report**
137 Boolean value (``true`` or ``false``) that indicates whether the
138 job name should be included in the report (normally only the URL
139 is included). Defaults to ``false``.
140 ``job_name_in_report=true``
141
Arx Cruzb1b010d2013-10-28 19:49:59 -0200142**zuul_url**
143 URL of Zuul's git repos, accessible to test workers.
144 Usually "http://zuul.example.com/p".
145
Joshua Hesketh5fea8672013-08-19 17:32:01 +1000146smtp
147""""
148
149**server**
150 SMTP server hostname or address to use.
151 ``server=localhost``
152
153**default_from**
154 Who the email should appear to be sent from when emailing the report.
155 This can be overridden by individual pipelines.
156 ``default_from=zuul@example.com``
157
158**default_to**
159 Who the report should be emailed to by default.
160 This can be overridden by individual pipelines.
161 ``default_to=you@example.com``
162
James E. Blaircdd00072012-06-08 19:17:28 -0700163layout.yaml
164~~~~~~~~~~~
165
Clark Boylan00635dc2012-09-19 14:03:08 -0700166This is the main configuration file for Zuul, where all of the pipelines
James E. Blaircdd00072012-06-08 19:17:28 -0700167and projects are defined, what tests should be run, and what actions
Clark Boylan00635dc2012-09-19 14:03:08 -0700168Zuul should perform. There are three sections: pipelines, jobs, and
James E. Blaircdd00072012-06-08 19:17:28 -0700169projects.
170
James E. Blaire5a847f2012-07-10 15:29:14 -0700171.. _includes:
172
173Includes
174""""""""
175
176Custom functions to be used in Zuul's configuration may be provided
177using the ``includes`` directive. It accepts a list of files to
178include, and currently supports one type of inclusion, a python file::
179
180 includes:
181 - python-file: local_functions.py
182
183**python-file**
184 The path to a python file. The file will be loaded and objects that
185 it defines will be placed in a special environment which can be
186 referenced in the Zuul configuration. Currently only the
187 parameter-function attribute of a Job uses this feature.
188
Clark Boylan00635dc2012-09-19 14:03:08 -0700189Pipelines
190"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700191
Clark Boylan00635dc2012-09-19 14:03:08 -0700192Zuul can have any number of independent pipelines. Whenever a matching
193Gerrit event is found for a pipeline, that event is added to the
194pipeline, and the jobs specified for that pipeline are run. When all
195jobs specified for the pipeline that were triggered by an event are
196completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700197
Clark Boylan00635dc2012-09-19 14:03:08 -0700198There are no pre-defined pipelines in Zuul, rather you can define
199whatever pipelines you need in the layout file. This is a very flexible
200system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700201
Clark Boylan00635dc2012-09-19 14:03:08 -0700202Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700203explanation of each of the parameters::
204
205 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700206 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700207 trigger:
James E. Blair6c358e72013-07-29 17:06:47 -0700208 gerrit:
209 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700210 success:
211 verified: 1
212 failure:
213 verified: -1
214
215**name**
216 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700217 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700218
James E. Blair8dbd56a2012-12-22 10:55:10 -0800219**description**
220 This is an optional field that may be used to provide a textual
221 description of the pipeline.
222
James E. Blair56370192013-01-14 15:47:28 -0800223**success-message**
224 An optional field that supplies the introductory text in message
225 reported back to Gerrit when all the voting builds are successful.
226 Defaults to "Build successful."
227
228**failure-message**
229 An optional field that supplies the introductory text in message
230 reported back to Gerrit when at least one voting build fails.
231 Defaults to "Build failed."
232
James E. Blaircdd00072012-06-08 19:17:28 -0700233**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700234 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700235
Clark Boylan00635dc2012-09-19 14:03:08 -0700236 *IndependentPipelineManager*
237 Every event in this pipeline should be treated as independent of
238 other events in the pipeline. This is appropriate when the order of
239 events in the pipeline doesn't matter because the results of the
240 actions this pipeline performs can not affect other events in the
241 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700242 you may want to run tests on that change to provide early feedback
243 to reviewers. At the end of the tests, the change is not going to
244 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700245 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700246
Clark Boylan00635dc2012-09-19 14:03:08 -0700247 Another type of pipeline that is independent is a post-merge
248 pipeline. In that case, the changes have already merged, so the
249 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700250
Clark Boylan00635dc2012-09-19 14:03:08 -0700251 *DependentPipelineManager*
252 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700253 that every change is tested exactly as it is going to be merged
254 into the repository. An ideal gating system would test one change
255 at a time, applied to the tip of the repository, and only if that
256 change passed tests would it be merged. Then the next change in
257 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700258 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700259 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700260 their entry into the pipeline. It begins testing all changes in
261 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700262 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700263 merged in parallel. If a change near the front of the pipeline
264 fails its tests, each change behind it ignores whatever tests have
265 been completed and are tested again without the change in front.
266 This way gate tests may run in parallel but still be tested
267 correctly, exactly as they will appear in the repository when
268 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700269
Clark Boylan00635dc2012-09-19 14:03:08 -0700270 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700271 it analyzes the jobs that are triggered by different projects, and
272 if those projects have jobs in common, it treats those projects as
273 related, and they share a single virtual queue of changes. Thus,
274 if there is a job that performs integration testing on two
275 projects, those two projects will automatically share a virtual
276 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700277 will be part of a separate virtual change queue, and changes to
278 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700279
280 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700281 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700282
283**trigger**
James E. Blair6c358e72013-07-29 17:06:47 -0700284 Exactly one trigger source must be supplied for each pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700285 Triggers are not exclusive -- matching events may be placed in
James E. Blair6c358e72013-07-29 17:06:47 -0700286 multiple pipelines, and they will behave independently in each of
287 the pipelines they match. You may select from the following:
James E. Blaircdd00072012-06-08 19:17:28 -0700288
James E. Blair6c358e72013-07-29 17:06:47 -0700289 **gerrit**
290 This describes what Gerrit events should be placed in the
291 pipeline. Multiple gerrit triggers may be listed. Further
292 parameters describe the kind of events that match:
James E. Blaircdd00072012-06-08 19:17:28 -0700293
James E. Blair6c358e72013-07-29 17:06:47 -0700294 *event*
295 The event name from gerrit. Examples: ``patchset-created``,
296 ``comment-added``, ``ref-updated``. This field is treated as a
297 regular expression.
James E. Blaircdd00072012-06-08 19:17:28 -0700298
James E. Blair6c358e72013-07-29 17:06:47 -0700299 *branch*
300 The branch associated with the event. Example: ``master``. This
301 field is treated as a regular expression, and multiple branches may
302 be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700303
James E. Blair6c358e72013-07-29 17:06:47 -0700304 *ref*
305 On ref-updated events, the branch parameter is not used, instead the
306 ref is provided. Currently Gerrit has the somewhat idiosyncratic
307 behavior of specifying bare refs for branch names (e.g., ``master``),
308 but full ref names for other kinds of refs (e.g., ``refs/tags/foo``).
309 Zuul matches what you put here exactly against what Gerrit
310 provides. This field is treated as a regular expression, and
311 multiple refs may be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700312
James E. Blair6c358e72013-07-29 17:06:47 -0700313 *approval*
314 This is only used for ``comment-added`` events. It only matches if
315 the event has a matching approval associated with it. Example:
316 ``code-review: 2`` matches a ``+2`` vote on the code review category.
317 Multiple approvals may be listed.
Antoine Mussob4e809e2012-12-06 16:58:06 +0100318
James E. Blair6c358e72013-07-29 17:06:47 -0700319 *email_filter*
320 This is used for any event. It takes a regex applied on the performer
Michael Prokop526926a2013-10-24 16:16:57 +0200321 email, i.e. Gerrit account email address. If you want to specify
James E. Blair6c358e72013-07-29 17:06:47 -0700322 several email filters, you must use a YAML list. Make sure to use non
323 greedy matchers and to escapes dots!
324 Example: ``email_filter: ^.*?@example\.org$``.
325
326 *comment_filter*
327 This is only used for ``comment-added`` events. It accepts a list of
328 regexes that are searched for in the comment string. If any of these
329 regexes matches a portion of the comment string the trigger is
330 matched. ``comment_filter: retrigger`` will match when comments
331 containing 'retrigger' somewhere in the comment text are added to a
332 change.
Clark Boylanb9bcb402012-06-29 17:44:05 -0700333
James E. Blair63bb0ef2013-07-29 17:14:51 -0700334 **timer**
335 This trigger will run based on a cron-style time specification.
336 It will enqueue an event into its pipeline for every project
337 defined in the configuration. Any job associated with the
338 pipeline will run in response to that event.
339
340 *time*
341 The time specification in cron syntax. Only the 5 part syntax is
342 supported, not the symbolic names. Example: ``0 0 * * *`` runs
343 at midnight.
344
345
James E. Blair2fa50962013-01-30 21:50:41 -0800346**dequeue-on-new-patchset**
347 Normally, if a new patchset is uploaded to a change that is in a
348 pipeline, the existing entry in the pipeline will be removed (with
349 jobs canceled and any dependent changes that can no longer merge as
350 well. To suppress this behavior (and allow jobs to continue
351 running), set this to ``false``. Default: ``true``.
352
James E. Blaircdd00072012-06-08 19:17:28 -0700353**success**
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000354 Describes where Zuul should report to if all the jobs complete
355 successfully.
James E. Blaircdd00072012-06-08 19:17:28 -0700356 This section is optional; if it is omitted, Zuul will run jobs and
357 do nothing on success; it will not even report a message to Gerrit.
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000358 If the section is present, the listed reporter plugins will be
359 asked to report on the jobs.
360 Each reporter's value dictionary is handled by the reporter. See
361 reporters for more details.
James E. Blaircdd00072012-06-08 19:17:28 -0700362
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400363**failure**
James E. Blaircdd00072012-06-08 19:17:28 -0700364 Uses the same syntax as **success**, but describes what Zuul should
365 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700366
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400367**start**
James E. Blairdc253862012-06-13 17:12:42 -0700368 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700369 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700370 for example, to reset the value of the Verified review category.
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400371
James E. Blair64ed6f22013-07-10 14:07:23 -0700372**precedence**
373 Indicates how the build scheduler should prioritize jobs for
374 different pipelines. Each pipeline may have one precedence, jobs
375 for pipelines with a higher precedence will be run before ones with
376 lower. The value should be one of ``high``, ``normal``, or ``low``.
377 Default: ``normal``.
378
Clark Boylan00635dc2012-09-19 14:03:08 -0700379Some example pipeline configurations are included in the sample layout
380file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700381
382 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700383 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700384 trigger:
385 - event: patchset-created
386 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000387 gerrit:
388 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700389 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000390 gerrit:
391 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700392
393This will trigger jobs each time a new patchset (or change) is
394uploaded to Gerrit, and report +/-1 values to Gerrit in the
395``verified`` review category. ::
396
397 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700398 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700399 trigger:
400 - event: comment-added
401 approval:
402 - approved: 1
403 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000404 gerrit:
405 verified: 2
406 submit: true
James E. Blaircdd00072012-06-08 19:17:28 -0700407 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000408 gerrit:
409 verified: -2
James E. Blaircdd00072012-06-08 19:17:28 -0700410
411This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
412``approved`` review category in Gerrit (a non-standard category).
413Changes will be tested in such a way as to guarantee that they will be
414merged exactly as tested, though that will happen in parallel by
415creating a virtual queue of dependent changes and performing
416speculative execution of jobs. ::
417
418 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700419 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700420 trigger:
421 - event: ref-updated
422 ref: ^(?!refs/).*$
423
424This will trigger jobs whenever a change is merged to a named branch
425(e.g., ``master``). No output will be reported to Gerrit. This is
426useful for side effects such as creating per-commit tarballs. ::
427
428 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700429 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700430 trigger:
431 - event: patchset-created
432
433This also triggers jobs when changes are uploaded to Gerrit, but no
434results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200435development and not yet ready to be presented to developers. ::
436
437 pipelines:
438 - name: post-merge
439 manager: IndependentPipelineManager
440 trigger:
441 - event: change-merged
442 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000443 gerrit:
444 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200445 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000446 gerrit:
447 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200448
449The ``change-merged`` events happen when a change has been merged in the git
450repository. The change is thus closed and Gerrit will not accept modifications
451to the review scoring such as ``code-review`` or ``verified``. By using the
452``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
453``gerrit review`` command, thus making sure the message is actually
454sent back to Gerrit regardless of approval scores.
455That kind of pipeline is nice to run regression or performance tests.
456
457.. note::
458 The ``change-merged`` event does not include the commit sha1 which can be
459 hazardous, it would let you report back to Gerrit though. If you were to
Michael Prokop526926a2013-10-24 16:16:57 +0200460 build a tarball for a specific commit, you should consider instead using
Antoine Mussoce333842012-10-16 14:42:35 +0200461 the ``ref-updated`` event which does include the commit sha1 (but lack the
462 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700463
464Jobs
465""""
466
467The jobs section is optional, and can be used to set attributes of
468jobs that are independent of their association with a project. For
469example, if a job should return a customized message on failure, that
470may be specified here. Otherwise, Zuul does not need to be told about
471each job as it builds a list from the project specification.
472
473**name**
474 The name of the job. This field is treated as a regular expression
475 and will be applied to each job that matches.
476
James E. Blaire5a847f2012-07-10 15:29:14 -0700477**failure-message (optional)**
478 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700479
James E. Blaire5a847f2012-07-10 15:29:14 -0700480**success-message (optional)**
481 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700482
James E. Blair6aea36d2012-12-17 13:03:24 -0800483**failure-pattern (optional)**
484 The URL that should be reported to Gerrit if the job fails.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700485 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800486 zuul.conf. May be supplied as a string pattern with substitutions
487 as described in url_pattern in :ref:`zuulconf`.
488
489**success-pattern (optional)**
490 The URL that should be reported to Gerrit if the job succeeds.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700491 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800492 zuul.conf. May be supplied as a string pattern with substitutions
493 as described in url_pattern in :ref:`zuulconf`.
494
James E. Blair222d4982012-07-16 09:31:19 -0700495**hold-following-changes (optional)**
496 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700497 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700498 succeeds before launching. If this is applied to a very short job
499 that can predict whether longer jobs will fail early, this can be
500 used to reduce the number of jobs that Zuul will launch and
501 ultimately have to cancel. In that case, a small amount of
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400502 parallelization of jobs is traded for more efficient use of testing
James E. Blair222d4982012-07-16 09:31:19 -0700503 resources. On the other hand, to apply this to a long running job
504 would largely defeat the parallelization of dependent change testing
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400505 that is the main feature of Zuul. Default: ``false``.
James E. Blair222d4982012-07-16 09:31:19 -0700506
James E. Blaire5a847f2012-07-10 15:29:14 -0700507**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700508 This job should only be run on matching branches. This field is
509 treated as a regular expression and multiple branches may be
510 listed.
511
James E. Blair70c71582013-03-06 08:50:50 -0800512**files (optional)**
513 This job should only be run if at least one of the files involved in
514 the change (added, deleted, or modified) matches at least one of the
515 file patterns listed here. This field is treated as a regular
516 expression and multiple expressions may be listed.
517
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400518**voting (optional)**
519 Boolean value (``true`` or ``false``) that indicates whatever
520 a job is voting or not. Default: ``true``.
521
James E. Blaire5a847f2012-07-10 15:29:14 -0700522**parameter-function (optional)**
523 Specifies a function that should be applied to the parameters before
524 the job is launched. The function should be defined in a python file
525 included with the :ref:`includes` directive. The function
526 should have the following signature:
527
James E. Blaird0470972013-07-29 10:05:43 -0700528 .. function:: parameters(item, job, parameters)
James E. Blaire5a847f2012-07-10 15:29:14 -0700529
530 Manipulate the parameters passed to a job before a build is
531 launched. The ``parameters`` dictionary will already contain the
532 standard Zuul job parameters, and is expected to be modified
533 in-place.
534
James E. Blaird78576a2013-07-09 10:39:17 -0700535 :param item: the current queue item
536 :type item: zuul.model.QueueItem
James E. Blaird0470972013-07-29 10:05:43 -0700537 :param job: the job about to be run
538 :type job: zuul.model.Job
James E. Blaire5a847f2012-07-10 15:29:14 -0700539 :param parameters: parameters to be passed to the job
540 :type parameters: dict
541
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700542 If the parameter **ZUUL_NODE** is set by this function, then it will
543 be used to specify on what node (or class of node) the job should be
544 run.
545
James E. Blaircdd00072012-06-08 19:17:28 -0700546Here is an example of setting the failure message for jobs that check
547whether a change merges cleanly::
548
549 - name: ^.*-merge$
550 failure-message: This change was unable to be automatically merged
551 with the current state of the repository. Please rebase your
552 change and upload a new patchset.
553
554Projects
555""""""""
556
Clark Boylan00635dc2012-09-19 14:03:08 -0700557The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700558for events associated with each project. It contains a list of
559projects. Here is an example::
560
561 - name: example/project
562 check:
563 - project-merge:
564 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700565 - project-pep8
566 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700567 gate:
568 - project-merge:
569 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700570 - project-pep8
571 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700572 post:
573 - project-publish
574
575**name**
576 The name of the project (as known by Gerrit).
577
James E. Blair19deff22013-08-25 13:17:35 -0700578**merge-mode (optional)**
579 An optional value that indicates what strategy should be used to
580 merge changes to this project. Supported values are:
581
582 ** merge-resolve **
583 Equivalent to 'git merge -s resolve'. This corresponds closely to
584 what Gerrit performs (using JGit) for a project if the "Merge if
585 necessary" merge mode is selected and "Automatically resolve
586 conflicts" is checked. This is the default.
587
588 ** merge **
589 Equivalent to 'git merge'.
590
591 ** cherry-pick **
592 Equivalent to 'git cherry-pick'.
593
Clark Boylan00635dc2012-09-19 14:03:08 -0700594This is followed by a section for each of the pipelines defined above.
595Pipelines may be omitted if no jobs should run for this project in a
596given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700597executed are listed. If a job is entered as a dictionary key, then
598jobs contained within that key are only executed if the key job
599succeeds. In the above example, project-unittest, project-pep8, and
600project-pyflakes are only executed if project-merge succeeds. This
601can help avoid running unnecessary jobs.
602
Paul Belangerffef9e42013-02-11 22:15:18 -0500603.. seealso:: The OpenStack Zuul configuration for a comprehensive example: https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/zuul/layout.yaml
James E. Blaircdd00072012-06-08 19:17:28 -0700604
Antoine Musso80edd5a2013-02-13 15:37:53 +0100605Project Templates
606"""""""""""""""""
607
Michael Prokop526926a2013-10-24 16:16:57 +0200608Whenever you have lot of similar projects (such as plugins for a project) you
Antoine Musso80edd5a2013-02-13 15:37:53 +0100609will most probably want to use the same pipeline configurations. The
610project templates let you define pipelines and job name templates to trigger.
611One can then just apply the template on its project which make it easier to
Michael Prokop526926a2013-10-24 16:16:57 +0200612update several similar projects. As an example::
Antoine Musso80edd5a2013-02-13 15:37:53 +0100613
614 project-templates:
615 # Name of the template
616 - name: plugin-triggering
617 # Definition of pipelines just like for a `project`
618 check:
619 - '{jobprefix}-merge':
620 - '{jobprefix}-pep8'
621 - '{jobprefix}-pyflakes'
622 gate:
623 - '{jobprefix}-merge':
624 - '{jobprefix}-unittest'
625 - '{jobprefix}-pep8'
626 - '{jobprefix}-pyflakes'
627
628In your projects definition, you will then apply the template using the template
629key::
630
631 projects:
632 - name: plugin/foobar
633 template:
634 - name: plugin-triggering
635 jobprefix: plugin-foobar
636
637You can pass several parameters to a template. A ``parameter`` value will be
638used for expansion of ``{parameter}`` in the template strings.
James E. Blaircdd00072012-06-08 19:17:28 -0700639
640logging.conf
641~~~~~~~~~~~~
642This file is optional. If provided, it should be a standard
643:mod:`logging.config` module configuration file. If not present, Zuul will
644output all log messages of DEBUG level or higher to the console.
645
646Starting Zuul
647-------------
648
649To start Zuul, run **zuul-server**::
650
Antoine Mussob3aa8282013-04-19 15:16:59 +0200651 usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]
James E. Blaircdd00072012-06-08 19:17:28 -0700652
653 Project gating system.
654
655 optional arguments:
656 -h, --help show this help message and exit
657 -c CONFIG specify the config file
Antoine Mussob3aa8282013-04-19 15:16:59 +0200658 -l LAYOUT specify the layout file
James E. Blaircdd00072012-06-08 19:17:28 -0700659 -d do not run as a daemon
Antoine Mussob3aa8282013-04-19 15:16:59 +0200660 -t validate layout file syntax
661 --version show zuul version
James E. Blaircdd00072012-06-08 19:17:28 -0700662
663You may want to use the ``-d`` argument while you are initially setting
664up Zuul so you can detect any configuration errors quickly. Under
665normal operation, omit ``-d`` and let Zuul run as a daemon.
666
667If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
668stop executing new jobs, wait until all executing jobs are finished,
669reload its configuration, and resume. Any values in any of the
670configuration files may be changed, except the location of Zuul's PID
671file (a change to that will be ignored until Zuul is restarted).
Clark Boylanf231fa22013-02-08 12:28:53 -0800672
673If you send a SIGUSR1 to the zuul-server process, Zuul will stop
674executing new jobs, wait until all executing jobs are finished,
675then exit. While waiting to exit Zuul will queue Gerrit events and
676save these events prior to exiting. When Zuul starts again it will
677read these saved events and act on them.
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000678
Michael Prokop526926a2013-10-24 16:16:57 +0200679If you need to abort Zuul and intend to manually requeue changes for
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000680jobs which were running in its pipelines, prior to terminating you can
681use the zuul-changes.py tool script to simplify the process. For
682example, this would give you a list of Gerrit commands to reverify or
683recheck changes for the gate and check pipelines respectively::
684
685 ./tools/zuul-changes.py --review-host=review.openstack.org \
686 http://zuul.openstack.org/ gate 'reverify no bug'
687 ./tools/zuul-changes.py --review-host=review.openstack.org \
688 http://zuul.openstack.org/ check 'recheck no bug'
Clark Boylanfba9b242013-08-20 10:11:17 -0700689
690If you send a SIGUSR2 to the zuul-server process, Zuul will dump a stack
691trace for each running thread into its debug log. This is useful for
692tracking down deadlock or otherwise slow threads.