blob: b4adc4da6e488f9a1a4421c3ddbabf855ea739e4 [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. Blair87650fa2014-01-08 11:43:23 +0800163replication
164"""""""""""
165
166Zuul can push the refs it creates to any number of servers. To do so,
167list the git push URLs in this section, one per line as follows::
168
169 [replication]
170 url1=ssh://user@host1.example.com:port/path/to/repo
171 url2=ssh://user@host2.example.com:port/path/to/repo
172
James E. Blaircdd00072012-06-08 19:17:28 -0700173layout.yaml
174~~~~~~~~~~~
175
Clark Boylan00635dc2012-09-19 14:03:08 -0700176This is the main configuration file for Zuul, where all of the pipelines
James E. Blaircdd00072012-06-08 19:17:28 -0700177and projects are defined, what tests should be run, and what actions
Clark Boylan00635dc2012-09-19 14:03:08 -0700178Zuul should perform. There are three sections: pipelines, jobs, and
James E. Blaircdd00072012-06-08 19:17:28 -0700179projects.
180
James E. Blaire5a847f2012-07-10 15:29:14 -0700181.. _includes:
182
183Includes
184""""""""
185
186Custom functions to be used in Zuul's configuration may be provided
187using the ``includes`` directive. It accepts a list of files to
188include, and currently supports one type of inclusion, a python file::
189
190 includes:
191 - python-file: local_functions.py
192
193**python-file**
194 The path to a python file. The file will be loaded and objects that
195 it defines will be placed in a special environment which can be
196 referenced in the Zuul configuration. Currently only the
197 parameter-function attribute of a Job uses this feature.
198
Clark Boylan00635dc2012-09-19 14:03:08 -0700199Pipelines
200"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700201
Clark Boylan00635dc2012-09-19 14:03:08 -0700202Zuul can have any number of independent pipelines. Whenever a matching
203Gerrit event is found for a pipeline, that event is added to the
204pipeline, and the jobs specified for that pipeline are run. When all
205jobs specified for the pipeline that were triggered by an event are
206completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700207
Clark Boylan00635dc2012-09-19 14:03:08 -0700208There are no pre-defined pipelines in Zuul, rather you can define
209whatever pipelines you need in the layout file. This is a very flexible
210system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700211
Clark Boylan00635dc2012-09-19 14:03:08 -0700212Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700213explanation of each of the parameters::
214
215 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700216 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700217 trigger:
James E. Blair6c358e72013-07-29 17:06:47 -0700218 gerrit:
219 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700220 success:
221 verified: 1
222 failure:
223 verified: -1
224
225**name**
226 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700227 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700228
James E. Blair8dbd56a2012-12-22 10:55:10 -0800229**description**
230 This is an optional field that may be used to provide a textual
231 description of the pipeline.
232
James E. Blair56370192013-01-14 15:47:28 -0800233**success-message**
234 An optional field that supplies the introductory text in message
235 reported back to Gerrit when all the voting builds are successful.
236 Defaults to "Build successful."
237
238**failure-message**
239 An optional field that supplies the introductory text in message
240 reported back to Gerrit when at least one voting build fails.
241 Defaults to "Build failed."
242
James E. Blaircdd00072012-06-08 19:17:28 -0700243**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700244 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700245
Clark Boylan00635dc2012-09-19 14:03:08 -0700246 *IndependentPipelineManager*
247 Every event in this pipeline should be treated as independent of
248 other events in the pipeline. This is appropriate when the order of
249 events in the pipeline doesn't matter because the results of the
250 actions this pipeline performs can not affect other events in the
251 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700252 you may want to run tests on that change to provide early feedback
253 to reviewers. At the end of the tests, the change is not going to
254 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700255 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700256
Clark Boylan00635dc2012-09-19 14:03:08 -0700257 Another type of pipeline that is independent is a post-merge
258 pipeline. In that case, the changes have already merged, so the
259 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700260
Clark Boylan00635dc2012-09-19 14:03:08 -0700261 *DependentPipelineManager*
262 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700263 that every change is tested exactly as it is going to be merged
264 into the repository. An ideal gating system would test one change
265 at a time, applied to the tip of the repository, and only if that
266 change passed tests would it be merged. Then the next change in
267 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700268 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700269 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700270 their entry into the pipeline. It begins testing all changes in
271 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700272 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700273 merged in parallel. If a change near the front of the pipeline
274 fails its tests, each change behind it ignores whatever tests have
275 been completed and are tested again without the change in front.
276 This way gate tests may run in parallel but still be tested
277 correctly, exactly as they will appear in the repository when
278 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700279
Clark Boylan00635dc2012-09-19 14:03:08 -0700280 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700281 it analyzes the jobs that are triggered by different projects, and
282 if those projects have jobs in common, it treats those projects as
283 related, and they share a single virtual queue of changes. Thus,
284 if there is a job that performs integration testing on two
285 projects, those two projects will automatically share a virtual
286 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700287 will be part of a separate virtual change queue, and changes to
288 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700289
290 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700291 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700292
293**trigger**
James E. Blair6c358e72013-07-29 17:06:47 -0700294 Exactly one trigger source must be supplied for each pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700295 Triggers are not exclusive -- matching events may be placed in
James E. Blair6c358e72013-07-29 17:06:47 -0700296 multiple pipelines, and they will behave independently in each of
297 the pipelines they match. You may select from the following:
James E. Blaircdd00072012-06-08 19:17:28 -0700298
James E. Blair6c358e72013-07-29 17:06:47 -0700299 **gerrit**
300 This describes what Gerrit events should be placed in the
301 pipeline. Multiple gerrit triggers may be listed. Further
302 parameters describe the kind of events that match:
James E. Blaircdd00072012-06-08 19:17:28 -0700303
James E. Blair6c358e72013-07-29 17:06:47 -0700304 *event*
305 The event name from gerrit. Examples: ``patchset-created``,
306 ``comment-added``, ``ref-updated``. This field is treated as a
307 regular expression.
James E. Blaircdd00072012-06-08 19:17:28 -0700308
James E. Blair6c358e72013-07-29 17:06:47 -0700309 *branch*
310 The branch associated with the event. Example: ``master``. This
311 field is treated as a regular expression, and multiple branches may
312 be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700313
James E. Blair6c358e72013-07-29 17:06:47 -0700314 *ref*
315 On ref-updated events, the branch parameter is not used, instead the
316 ref is provided. Currently Gerrit has the somewhat idiosyncratic
317 behavior of specifying bare refs for branch names (e.g., ``master``),
318 but full ref names for other kinds of refs (e.g., ``refs/tags/foo``).
319 Zuul matches what you put here exactly against what Gerrit
320 provides. This field is treated as a regular expression, and
321 multiple refs may be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700322
James E. Blair6c358e72013-07-29 17:06:47 -0700323 *approval*
324 This is only used for ``comment-added`` events. It only matches if
325 the event has a matching approval associated with it. Example:
326 ``code-review: 2`` matches a ``+2`` vote on the code review category.
327 Multiple approvals may be listed.
Antoine Mussob4e809e2012-12-06 16:58:06 +0100328
James E. Blair6c358e72013-07-29 17:06:47 -0700329 *email_filter*
330 This is used for any event. It takes a regex applied on the performer
Michael Prokop526926a2013-10-24 16:16:57 +0200331 email, i.e. Gerrit account email address. If you want to specify
James E. Blair6c358e72013-07-29 17:06:47 -0700332 several email filters, you must use a YAML list. Make sure to use non
333 greedy matchers and to escapes dots!
334 Example: ``email_filter: ^.*?@example\.org$``.
335
Joshua Heskethb8a817e2013-12-27 11:21:38 +1100336 *username_filter*
337 This is used for any event. It takes a regex applied on the performer
338 username, i.e. Gerrit account name. If you want to specify several
339 username filters, you must use a YAML list. Make sure to use non greedy
340 matchers and to escapes dots!
341 Example: ``username_filter: ^jenkins$``.
342
James E. Blair6c358e72013-07-29 17:06:47 -0700343 *comment_filter*
344 This is only used for ``comment-added`` events. It accepts a list of
345 regexes that are searched for in the comment string. If any of these
346 regexes matches a portion of the comment string the trigger is
347 matched. ``comment_filter: retrigger`` will match when comments
348 containing 'retrigger' somewhere in the comment text are added to a
349 change.
Clark Boylanb9bcb402012-06-29 17:44:05 -0700350
James E. Blairc053d022014-01-22 14:57:33 -0800351 *require-approval*
352 This may be used for any event. It requires that a certain kind
353 of approval be present for the current patchset of the change (the
354 approval could be added by the event in question). It takes
355 several sub-parameters, all of which are optional and are combined
356 together so that there must be an approval matching all specified
357 requirements.
358
359 *username*
360 If present, an approval from this username is required.
361
362 *email-filter*
363 If present, an approval with this email address is required. It
364 is treated as a regular expression as above.
365
366 *older-than*
367 If present, the approval must be older than this amount of time
368 to match. Provide a time interval as a number with a suffix of
369 "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
370 (seconds). Example "48h" or "2d".
371
372 *newer-than*
373 If present, the approval must be newer than this amount of time
374 to match. Same format as "older-than".
375
376 Any other field is interpreted as a review category and value
377 pair. For example "verified: 1" would require that the approval
378 be for a +1 vote in the "Verified" column.
379
James E. Blair63bb0ef2013-07-29 17:14:51 -0700380 **timer**
381 This trigger will run based on a cron-style time specification.
382 It will enqueue an event into its pipeline for every project
383 defined in the configuration. Any job associated with the
384 pipeline will run in response to that event.
385
386 *time*
387 The time specification in cron syntax. Only the 5 part syntax is
388 supported, not the symbolic names. Example: ``0 0 * * *`` runs
389 at midnight.
390
391
James E. Blair2fa50962013-01-30 21:50:41 -0800392**dequeue-on-new-patchset**
393 Normally, if a new patchset is uploaded to a change that is in a
394 pipeline, the existing entry in the pipeline will be removed (with
395 jobs canceled and any dependent changes that can no longer merge as
396 well. To suppress this behavior (and allow jobs to continue
397 running), set this to ``false``. Default: ``true``.
398
James E. Blaircdd00072012-06-08 19:17:28 -0700399**success**
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000400 Describes where Zuul should report to if all the jobs complete
401 successfully.
James E. Blaircdd00072012-06-08 19:17:28 -0700402 This section is optional; if it is omitted, Zuul will run jobs and
403 do nothing on success; it will not even report a message to Gerrit.
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000404 If the section is present, the listed reporter plugins will be
405 asked to report on the jobs.
406 Each reporter's value dictionary is handled by the reporter. See
407 reporters for more details.
James E. Blaircdd00072012-06-08 19:17:28 -0700408
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400409**failure**
James E. Blaircdd00072012-06-08 19:17:28 -0700410 Uses the same syntax as **success**, but describes what Zuul should
411 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700412
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400413**start**
James E. Blairdc253862012-06-13 17:12:42 -0700414 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700415 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700416 for example, to reset the value of the Verified review category.
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400417
James E. Blair64ed6f22013-07-10 14:07:23 -0700418**precedence**
419 Indicates how the build scheduler should prioritize jobs for
420 different pipelines. Each pipeline may have one precedence, jobs
421 for pipelines with a higher precedence will be run before ones with
422 lower. The value should be one of ``high``, ``normal``, or ``low``.
423 Default: ``normal``.
424
Clark Boylan00635dc2012-09-19 14:03:08 -0700425Some example pipeline configurations are included in the sample layout
426file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700427
428 - name: check
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 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000433 gerrit:
434 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700435 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000436 gerrit:
437 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700438
439This will trigger jobs each time a new patchset (or change) is
440uploaded to Gerrit, and report +/-1 values to Gerrit in the
441``verified`` review category. ::
442
443 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700444 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700445 trigger:
446 - event: comment-added
447 approval:
448 - approved: 1
449 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000450 gerrit:
451 verified: 2
452 submit: true
James E. Blaircdd00072012-06-08 19:17:28 -0700453 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000454 gerrit:
455 verified: -2
James E. Blaircdd00072012-06-08 19:17:28 -0700456
457This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
458``approved`` review category in Gerrit (a non-standard category).
459Changes will be tested in such a way as to guarantee that they will be
460merged exactly as tested, though that will happen in parallel by
461creating a virtual queue of dependent changes and performing
462speculative execution of jobs. ::
463
464 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700465 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700466 trigger:
467 - event: ref-updated
468 ref: ^(?!refs/).*$
469
470This will trigger jobs whenever a change is merged to a named branch
471(e.g., ``master``). No output will be reported to Gerrit. This is
472useful for side effects such as creating per-commit tarballs. ::
473
474 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700475 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700476 trigger:
477 - event: patchset-created
478
479This also triggers jobs when changes are uploaded to Gerrit, but no
480results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200481development and not yet ready to be presented to developers. ::
482
483 pipelines:
484 - name: post-merge
485 manager: IndependentPipelineManager
486 trigger:
487 - event: change-merged
488 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000489 gerrit:
490 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200491 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000492 gerrit:
493 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200494
495The ``change-merged`` events happen when a change has been merged in the git
496repository. The change is thus closed and Gerrit will not accept modifications
497to the review scoring such as ``code-review`` or ``verified``. By using the
498``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
499``gerrit review`` command, thus making sure the message is actually
500sent back to Gerrit regardless of approval scores.
501That kind of pipeline is nice to run regression or performance tests.
502
503.. note::
504 The ``change-merged`` event does not include the commit sha1 which can be
505 hazardous, it would let you report back to Gerrit though. If you were to
Michael Prokop526926a2013-10-24 16:16:57 +0200506 build a tarball for a specific commit, you should consider instead using
Antoine Mussoce333842012-10-16 14:42:35 +0200507 the ``ref-updated`` event which does include the commit sha1 (but lack the
508 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700509
510Jobs
511""""
512
513The jobs section is optional, and can be used to set attributes of
514jobs that are independent of their association with a project. For
515example, if a job should return a customized message on failure, that
516may be specified here. Otherwise, Zuul does not need to be told about
517each job as it builds a list from the project specification.
518
519**name**
520 The name of the job. This field is treated as a regular expression
521 and will be applied to each job that matches.
522
James E. Blaire5a847f2012-07-10 15:29:14 -0700523**failure-message (optional)**
524 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700525
James E. Blaire5a847f2012-07-10 15:29:14 -0700526**success-message (optional)**
527 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700528
James E. Blair6aea36d2012-12-17 13:03:24 -0800529**failure-pattern (optional)**
530 The URL that should be reported to Gerrit if the job fails.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700531 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800532 zuul.conf. May be supplied as a string pattern with substitutions
533 as described in url_pattern in :ref:`zuulconf`.
534
535**success-pattern (optional)**
536 The URL that should be reported to Gerrit if the job succeeds.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700537 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800538 zuul.conf. May be supplied as a string pattern with substitutions
539 as described in url_pattern in :ref:`zuulconf`.
540
James E. Blair222d4982012-07-16 09:31:19 -0700541**hold-following-changes (optional)**
542 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700543 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700544 succeeds before launching. If this is applied to a very short job
545 that can predict whether longer jobs will fail early, this can be
546 used to reduce the number of jobs that Zuul will launch and
547 ultimately have to cancel. In that case, a small amount of
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400548 parallelization of jobs is traded for more efficient use of testing
James E. Blair222d4982012-07-16 09:31:19 -0700549 resources. On the other hand, to apply this to a long running job
550 would largely defeat the parallelization of dependent change testing
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400551 that is the main feature of Zuul. Default: ``false``.
James E. Blair222d4982012-07-16 09:31:19 -0700552
James E. Blaire5a847f2012-07-10 15:29:14 -0700553**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700554 This job should only be run on matching branches. This field is
555 treated as a regular expression and multiple branches may be
556 listed.
557
James E. Blair70c71582013-03-06 08:50:50 -0800558**files (optional)**
559 This job should only be run if at least one of the files involved in
560 the change (added, deleted, or modified) matches at least one of the
561 file patterns listed here. This field is treated as a regular
562 expression and multiple expressions may be listed.
563
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400564**voting (optional)**
565 Boolean value (``true`` or ``false``) that indicates whatever
566 a job is voting or not. Default: ``true``.
567
James E. Blaire5a847f2012-07-10 15:29:14 -0700568**parameter-function (optional)**
569 Specifies a function that should be applied to the parameters before
570 the job is launched. The function should be defined in a python file
571 included with the :ref:`includes` directive. The function
572 should have the following signature:
573
James E. Blaird0470972013-07-29 10:05:43 -0700574 .. function:: parameters(item, job, parameters)
James E. Blaire5a847f2012-07-10 15:29:14 -0700575
576 Manipulate the parameters passed to a job before a build is
577 launched. The ``parameters`` dictionary will already contain the
578 standard Zuul job parameters, and is expected to be modified
579 in-place.
580
James E. Blaird78576a2013-07-09 10:39:17 -0700581 :param item: the current queue item
582 :type item: zuul.model.QueueItem
James E. Blaird0470972013-07-29 10:05:43 -0700583 :param job: the job about to be run
584 :type job: zuul.model.Job
James E. Blaire5a847f2012-07-10 15:29:14 -0700585 :param parameters: parameters to be passed to the job
586 :type parameters: dict
587
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700588 If the parameter **ZUUL_NODE** is set by this function, then it will
589 be used to specify on what node (or class of node) the job should be
590 run.
591
James E. Blaircdd00072012-06-08 19:17:28 -0700592Here is an example of setting the failure message for jobs that check
593whether a change merges cleanly::
594
595 - name: ^.*-merge$
596 failure-message: This change was unable to be automatically merged
597 with the current state of the repository. Please rebase your
598 change and upload a new patchset.
599
600Projects
601""""""""
602
Clark Boylan00635dc2012-09-19 14:03:08 -0700603The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700604for events associated with each project. It contains a list of
605projects. Here is an example::
606
607 - name: example/project
608 check:
609 - project-merge:
610 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700611 - project-pep8
612 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700613 gate:
614 - project-merge:
615 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700616 - project-pep8
617 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700618 post:
619 - project-publish
620
621**name**
622 The name of the project (as known by Gerrit).
623
James E. Blair19deff22013-08-25 13:17:35 -0700624**merge-mode (optional)**
625 An optional value that indicates what strategy should be used to
626 merge changes to this project. Supported values are:
627
628 ** merge-resolve **
629 Equivalent to 'git merge -s resolve'. This corresponds closely to
630 what Gerrit performs (using JGit) for a project if the "Merge if
631 necessary" merge mode is selected and "Automatically resolve
632 conflicts" is checked. This is the default.
633
634 ** merge **
635 Equivalent to 'git merge'.
636
637 ** cherry-pick **
638 Equivalent to 'git cherry-pick'.
639
Clark Boylan00635dc2012-09-19 14:03:08 -0700640This is followed by a section for each of the pipelines defined above.
641Pipelines may be omitted if no jobs should run for this project in a
642given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700643executed are listed. If a job is entered as a dictionary key, then
644jobs contained within that key are only executed if the key job
645succeeds. In the above example, project-unittest, project-pep8, and
646project-pyflakes are only executed if project-merge succeeds. This
647can help avoid running unnecessary jobs.
648
Paul Belangerffef9e42013-02-11 22:15:18 -0500649.. 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 -0700650
Antoine Musso80edd5a2013-02-13 15:37:53 +0100651Project Templates
652"""""""""""""""""
653
Michael Prokop526926a2013-10-24 16:16:57 +0200654Whenever you have lot of similar projects (such as plugins for a project) you
Antoine Musso80edd5a2013-02-13 15:37:53 +0100655will most probably want to use the same pipeline configurations. The
656project templates let you define pipelines and job name templates to trigger.
657One can then just apply the template on its project which make it easier to
Michael Prokop526926a2013-10-24 16:16:57 +0200658update several similar projects. As an example::
Antoine Musso80edd5a2013-02-13 15:37:53 +0100659
660 project-templates:
661 # Name of the template
662 - name: plugin-triggering
663 # Definition of pipelines just like for a `project`
664 check:
665 - '{jobprefix}-merge':
666 - '{jobprefix}-pep8'
667 - '{jobprefix}-pyflakes'
668 gate:
669 - '{jobprefix}-merge':
670 - '{jobprefix}-unittest'
671 - '{jobprefix}-pep8'
672 - '{jobprefix}-pyflakes'
673
674In your projects definition, you will then apply the template using the template
675key::
676
677 projects:
678 - name: plugin/foobar
679 template:
680 - name: plugin-triggering
681 jobprefix: plugin-foobar
682
James E. Blairaea6cf62013-12-16 15:38:12 -0800683You can pass several parameters to a template. A ``parameter`` value
684will be used for expansion of ``{parameter}`` in the template
685strings. The parameter ``name`` will be automatically provided and
686will contain the short name of the project, that is the portion of the
687project name after the last ``/`` character.
James E. Blaircdd00072012-06-08 19:17:28 -0700688
James E. Blair3e98c022013-12-16 15:25:38 -0800689Multiple templates can be combined in a project, and the jobs from all
690of those templates will be added to the project. Individual jobs may
691also be added::
692
693 projects:
694 - name: plugin/foobar
695 template:
696 - name: plugin-triggering
697 jobprefix: plugin-foobar
698 - name: plugin-extras
699 jobprefix: plugin-foobar
700 check:
701 - foobar-extra-special-job
702
703The order of the jobs listed in the project (which only affects the
704order of jobs listed on the report) will be the jobs from each
705template in the order listed, followed by any jobs individually listed
706for the project.
707
708Note that if multiple templates are used for a project and one
709template specifies a job that is also specified in another template,
710or specified in the project itself, those jobs will be duplicated in
711the resulting project configuration.
712
James E. Blaircdd00072012-06-08 19:17:28 -0700713logging.conf
714~~~~~~~~~~~~
715This file is optional. If provided, it should be a standard
716:mod:`logging.config` module configuration file. If not present, Zuul will
717output all log messages of DEBUG level or higher to the console.
718
719Starting Zuul
720-------------
721
722To start Zuul, run **zuul-server**::
723
Antoine Mussob3aa8282013-04-19 15:16:59 +0200724 usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]
James E. Blaircdd00072012-06-08 19:17:28 -0700725
726 Project gating system.
727
728 optional arguments:
729 -h, --help show this help message and exit
730 -c CONFIG specify the config file
Antoine Mussob3aa8282013-04-19 15:16:59 +0200731 -l LAYOUT specify the layout file
James E. Blaircdd00072012-06-08 19:17:28 -0700732 -d do not run as a daemon
Antoine Mussob3aa8282013-04-19 15:16:59 +0200733 -t validate layout file syntax
734 --version show zuul version
James E. Blaircdd00072012-06-08 19:17:28 -0700735
736You may want to use the ``-d`` argument while you are initially setting
737up Zuul so you can detect any configuration errors quickly. Under
738normal operation, omit ``-d`` and let Zuul run as a daemon.
739
740If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
741stop executing new jobs, wait until all executing jobs are finished,
742reload its configuration, and resume. Any values in any of the
743configuration files may be changed, except the location of Zuul's PID
744file (a change to that will be ignored until Zuul is restarted).
Clark Boylanf231fa22013-02-08 12:28:53 -0800745
746If you send a SIGUSR1 to the zuul-server process, Zuul will stop
747executing new jobs, wait until all executing jobs are finished,
748then exit. While waiting to exit Zuul will queue Gerrit events and
749save these events prior to exiting. When Zuul starts again it will
750read these saved events and act on them.
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000751
Michael Prokop526926a2013-10-24 16:16:57 +0200752If you need to abort Zuul and intend to manually requeue changes for
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000753jobs which were running in its pipelines, prior to terminating you can
754use the zuul-changes.py tool script to simplify the process. For
755example, this would give you a list of Gerrit commands to reverify or
756recheck changes for the gate and check pipelines respectively::
757
758 ./tools/zuul-changes.py --review-host=review.openstack.org \
759 http://zuul.openstack.org/ gate 'reverify no bug'
760 ./tools/zuul-changes.py --review-host=review.openstack.org \
761 http://zuul.openstack.org/ check 'recheck no bug'
Clark Boylanfba9b242013-08-20 10:11:17 -0700762
763If you send a SIGUSR2 to the zuul-server process, Zuul will dump a stack
764trace for each running thread into its debug log. This is useful for
765tracking down deadlock or otherwise slow threads.