blob: 98e4bb8a2a56714bf79621089dbae3a356714dd2 [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
Łukasz Jernaś048acb42014-03-02 18:49:41 +010013 other config files.
James E. Blaircdd00072012-06-08 19:17:28 -070014**layout.yaml**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010015 Project and pipeline configuration -- what Zuul does.
James E. Blaircdd00072012-06-08 19:17:28 -070016**logging.conf**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010017 Python logging config.
James E. Blaircdd00072012-06-08 19:17:28 -070018
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
Andreas Jaegerbcfbf932014-09-29 20:21:44 +020039<https://git.openstack.org/cgit/openstack-infra/zuul/tree/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**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010049 Port on which the Gearman server is listening.
James E. Blair1f4c2bb2013-04-26 08:40:46 -070050 ``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
James E. Blair0ac452e2015-07-22 09:05:16 -070059**listen_address**
60 IP address or domain name on which to listen (default: all addresses).
61 ``listen_address=127.0.0.1``
62
James E. Blair77cc7b82013-07-15 13:22:37 -070063**log_config**
64 Path to log config file for internal Gearman server.
65 ``log_config=/etc/zuul/gearman-logging.yaml``
66
Clark Boylan9b670902012-09-28 13:47:56 -070067zuul
68""""
69
Antoine Musso9adc6d42014-11-14 15:37:48 +010070.. _layout_config:
71
Clark Boylan9b670902012-09-28 13:47:56 -070072**layout_config**
James E. Blair4076e2b2014-01-28 12:42:20 -080073 Path to layout config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070074 ``layout_config=/etc/zuul/layout.yaml``
75
76**log_config**
James E. Blaira4430132014-02-17 08:32:07 -080077 Path to log config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070078 ``log_config=/etc/zuul/logging.yaml``
79
80**pidfile**
James E. Blaira4430132014-02-17 08:32:07 -080081 Path to PID lock file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070082 ``pidfile=/var/run/zuul/zuul.pid``
83
84**state_dir**
James E. Blair4076e2b2014-01-28 12:42:20 -080085 Path to directory that Zuul should save state to. Used by all Zuul
86 commands.
Clark Boylan9b670902012-09-28 13:47:56 -070087 ``state_dir=/var/lib/zuul``
88
James E. Blair4076e2b2014-01-28 12:42:20 -080089**report_times**
90 Boolean value (``true`` or ``false``) that determines if Zuul should
91 include elapsed times for each job in the textual report. Used by
92 zuul-server only.
93 ``report_times=true``
94
95**status_url**
96 URL that will be posted in Zuul comments made to Gerrit changes when
97 starting jobs for a change. Used by zuul-server only.
98 ``status_url=https://zuul.example.com/status``
99
Clark Boylane0b4bdb2014-06-03 17:01:25 -0700100**status_expiry**
101 Zuul will cache the status.json file for this many seconds. This is an
102 optional value and ``1`` is used by default.
103 ``status_expiry=1``
104
James E. Blair4076e2b2014-01-28 12:42:20 -0800105**url_pattern**
106 If you are storing build logs external to the system that originally
107 ran jobs and wish to link to those logs when Zuul makes comments on
108 Gerrit changes for completed jobs this setting configures what the
109 URLs for those links should be. Used by zuul-server only.
110 ``http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}``
111
112**job_name_in_report**
113 Boolean value (``true`` or ``false``) that indicates whether the
114 job name should be included in the report (normally only the URL
115 is included). Defaults to ``false``. Used by zuul-server only.
116 ``job_name_in_report=true``
117
118merger
119""""""
120
Clark Boylan9b670902012-09-28 13:47:56 -0700121**git_dir**
122 Directory that Zuul should clone local git repositories to.
123 ``git_dir=/var/lib/zuul/git``
124
Paul Belangerb67aba12013-05-13 19:22:14 -0400125**git_user_email**
126 Optional: Value to pass to `git config user.email`.
127 ``git_user_email=zuul@example.com``
128
129**git_user_name**
130 Optional: Value to pass to `git config user.name`.
131 ``git_user_name=zuul``
132
Arx Cruzb1b010d2013-10-28 19:49:59 -0200133**zuul_url**
James E. Blair4076e2b2014-01-28 12:42:20 -0800134 URL of this merger's git repos, accessible to test workers. Usually
135 "http://zuul.example.com/p" or "http://zuul-merger01.example.com/p"
136 depending on whether the merger is co-located with the Zuul server.
Arx Cruzb1b010d2013-10-28 19:49:59 -0200137
James E. Blaira4430132014-02-17 08:32:07 -0800138**log_config**
139 Path to log config file for the merger process.
140 ``log_config=/etc/zuul/logging.yaml``
141
142**pidfile**
143 Path to PID lock file for the merger process.
144 ``pidfile=/var/run/zuul-merger/merger.pid``
145
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100146.. _swift:
147
148swift
149"""""
150
151To send (optional) swift upload instructions this section must be
Antoine Musso62fa2d42014-06-04 22:55:23 +0200152present. Multiple destinations can be defined in the :ref:`jobs` section
153of the layout.
154
155If you are sending the temp-url-key or fetching the x-storage-url, you
156will need the python-swiftclient module installed.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100157
Joshua Heskethc4967502014-05-15 06:39:14 -0700158**X-Account-Meta-Temp-Url-Key** (optional)
159 This is the key used to sign the HMAC message. If you do not set a
160 key Zuul will generate one automatically.
161
162**Send-Temp-Url-Key** (optional)
163 Zuul can send the X-Account-Meta-Temp-Url-Key to swift for you if
164 you have set up the appropriate credentials in ``authurl`` below.
165 This isn't necessary if you know and have set your
166 X-Account-Meta-Temp-Url-Key.
Antoine Musso62fa2d42014-06-04 22:55:23 +0200167 If set, Zuul requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700168 ``default: true``
169
170**X-Storage-Url** (optional)
171 The storage URL is the destination to upload files into. If you do
172 not set this the ``authurl`` credentials are used to fetch the url
Antoine Musso62fa2d42014-06-04 22:55:23 +0200173 from swift and Zuul will requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700174
175**authurl** (optional)
176 The (keystone) Auth URL for swift.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100177 ``For example, https://identity.api.rackspacecloud.com/v2.0/``
Joshua Heskethc4967502014-05-15 06:39:14 -0700178 This is required if you have Send-Temp-Url-Key set to ``True`` or
179 if you have not supplied the X-Storage-Url.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100180
181Any of the `swiftclient connection parameters`_ can also be defined
182here by the same name. Including the os_options by their key name (
183``for example tenant_id``)
184
185.. _swiftclient connection parameters: http://docs.openstack.org/developer/python-swiftclient/swiftclient.html#module-swiftclient.client
186
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100187**region_name** (optional)
188 The region name holding the swift container
189 ``For example, SYD``
190
191Each destination defined by the :ref:`jobs` will have the following
192default values that it may overwrite.
193
194**default_container** (optional)
195 Container name to place the log into
196 ``For example, logs``
197
198**default_expiry** (optional)
199 How long the signed destination should be available for
200 ``default: 7200 (2hrs)``
201
202**default_max_file_size** (optional)
203 The maximum size of an individual file
204 ``default: 104857600 (100MB)``
205
206**default_max_file_count** (optional)
207 The maximum number of separate files to allow
208 ``default: 10``
209
210**default_logserver_prefix**
211 Provide a URL to the CDN or logserver app so that a worker knows
212 what URL to return. The worker should return the logserver_prefix
213 url and the object path.
214 ``For example: http://logs.example.org/server.app?obj=``
215
Joshua Heskethfe485c62015-08-11 23:42:34 +1000216.. _connection:
217
218connection ArbitraryName
219""""""""""""""""""""""""
220
221A connection can be listed with any arbitrary name. The required
222parameters are specified in the :ref:`connections` documentation
223depending on what driver you are using.
224
225.. _layoutyaml:
226
James E. Blaircdd00072012-06-08 19:17:28 -0700227layout.yaml
228~~~~~~~~~~~
229
Clark Boylan00635dc2012-09-19 14:03:08 -0700230This is the main configuration file for Zuul, where all of the pipelines
James E. Blaircdd00072012-06-08 19:17:28 -0700231and projects are defined, what tests should be run, and what actions
Clark Boylan00635dc2012-09-19 14:03:08 -0700232Zuul should perform. There are three sections: pipelines, jobs, and
James E. Blaircdd00072012-06-08 19:17:28 -0700233projects.
234
James E. Blaire5a847f2012-07-10 15:29:14 -0700235.. _includes:
236
237Includes
238""""""""
239
240Custom functions to be used in Zuul's configuration may be provided
241using the ``includes`` directive. It accepts a list of files to
242include, and currently supports one type of inclusion, a python file::
243
244 includes:
245 - python-file: local_functions.py
246
247**python-file**
Antoine Musso9adc6d42014-11-14 15:37:48 +0100248 The path to a python file (either an absolute path or relative to the
249 directory name of :ref:`layout_config <layout_config>`). The
250 file will be loaded and objects that it defines will be placed in a
251 special environment which can be referenced in the Zuul configuration.
252 Currently only the parameter-function attribute of a Job uses this
253 feature.
James E. Blaire5a847f2012-07-10 15:29:14 -0700254
Clark Boylan00635dc2012-09-19 14:03:08 -0700255Pipelines
256"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700257
Clark Boylan00635dc2012-09-19 14:03:08 -0700258Zuul can have any number of independent pipelines. Whenever a matching
259Gerrit event is found for a pipeline, that event is added to the
260pipeline, and the jobs specified for that pipeline are run. When all
261jobs specified for the pipeline that were triggered by an event are
262completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700263
Clark Boylan00635dc2012-09-19 14:03:08 -0700264There are no pre-defined pipelines in Zuul, rather you can define
265whatever pipelines you need in the layout file. This is a very flexible
266system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700267
Clark Boylan00635dc2012-09-19 14:03:08 -0700268Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700269explanation of each of the parameters::
270
271 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700272 manager: IndependentPipelineManager
Joshua Heskethfe485c62015-08-11 23:42:34 +1000273 source: my_gerrit
James E. Blaircdd00072012-06-08 19:17:28 -0700274 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000275 my_gerrit:
James E. Blair6c358e72013-07-29 17:06:47 -0700276 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700277 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000278 my_gerrit:
279 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700280 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000281 my_gerrit
282 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700283
284**name**
285 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700286 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700287
James E. Blair8dbd56a2012-12-22 10:55:10 -0800288**description**
289 This is an optional field that may be used to provide a textual
290 description of the pipeline.
291
James E. Blairc0dedf82014-08-06 09:37:52 -0700292**source**
Joshua Heskethfe485c62015-08-11 23:42:34 +1000293 A required field that specifies a connection that provides access to
294 the change objects that this pipeline operates on. The name of the
295 connection as per the zuul.conf should be specified. The driver used
296 for the connection named will be the source. Currently only ``gerrit``
297 drivers are supported.
James E. Blairc0dedf82014-08-06 09:37:52 -0700298
James E. Blair56370192013-01-14 15:47:28 -0800299**success-message**
300 An optional field that supplies the introductory text in message
301 reported back to Gerrit when all the voting builds are successful.
302 Defaults to "Build successful."
303
304**failure-message**
305 An optional field that supplies the introductory text in message
306 reported back to Gerrit when at least one voting build fails.
307 Defaults to "Build failed."
308
Joshua Heskethb7179772014-01-30 23:30:46 +1100309**merge-failure-message**
310 An optional field that supplies the introductory text in message
311 reported back to Gerrit when a change fails to merge with the
312 current state of the repository.
313 Defaults to "Merge failed."
314
Joshua Hesketh3979e3e2014-03-04 11:21:10 +1100315**footer-message**
316 An optional field to supply additional information after test results.
317 Useful for adding information about the CI system such as debugging
318 and contact details.
319
James E. Blaircdd00072012-06-08 19:17:28 -0700320**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700321 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700322
Clark Boylan00635dc2012-09-19 14:03:08 -0700323 *IndependentPipelineManager*
324 Every event in this pipeline should be treated as independent of
325 other events in the pipeline. This is appropriate when the order of
326 events in the pipeline doesn't matter because the results of the
327 actions this pipeline performs can not affect other events in the
328 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700329 you may want to run tests on that change to provide early feedback
330 to reviewers. At the end of the tests, the change is not going to
331 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700332 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700333
Clark Boylan00635dc2012-09-19 14:03:08 -0700334 Another type of pipeline that is independent is a post-merge
335 pipeline. In that case, the changes have already merged, so the
336 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700337
Clark Boylan00635dc2012-09-19 14:03:08 -0700338 *DependentPipelineManager*
339 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700340 that every change is tested exactly as it is going to be merged
341 into the repository. An ideal gating system would test one change
342 at a time, applied to the tip of the repository, and only if that
343 change passed tests would it be merged. Then the next change in
344 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700345 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700346 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700347 their entry into the pipeline. It begins testing all changes in
348 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700349 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700350 merged in parallel. If a change near the front of the pipeline
351 fails its tests, each change behind it ignores whatever tests have
352 been completed and are tested again without the change in front.
353 This way gate tests may run in parallel but still be tested
354 correctly, exactly as they will appear in the repository when
355 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700356
Clark Boylan00635dc2012-09-19 14:03:08 -0700357 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700358 it analyzes the jobs that are triggered by different projects, and
359 if those projects have jobs in common, it treats those projects as
360 related, and they share a single virtual queue of changes. Thus,
361 if there is a job that performs integration testing on two
362 projects, those two projects will automatically share a virtual
363 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700364 will be part of a separate virtual change queue, and changes to
365 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700366
367 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700368 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700369
370**trigger**
James E. Blairc494d542014-08-06 09:23:52 -0700371 At least one trigger source must be supplied for each pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700372 Triggers are not exclusive -- matching events may be placed in
James E. Blair6c358e72013-07-29 17:06:47 -0700373 multiple pipelines, and they will behave independently in each of
Joshua Heskethfe485c62015-08-11 23:42:34 +1000374 the pipelines they match.
James E. Blaircdd00072012-06-08 19:17:28 -0700375
Joshua Heskethfe485c62015-08-11 23:42:34 +1000376 Triggers are loaded from their connection name. The driver type of
377 the connection will dictate which options are available.
378 See :doc:`triggers`.
James E. Blairc494d542014-08-06 09:23:52 -0700379
James E. Blair11041d22014-05-02 14:49:53 -0700380**require**
381 If this section is present, it established pre-requisites for any
382 kind of item entering the Pipeline. Regardless of how the item is
383 to be enqueued (via any trigger or automatic dependency resolution),
384 the conditions specified here must be met or the item will not be
385 enqueued.
386
Antoine Musso27ab0d52014-10-22 14:20:17 +0200387.. _pipeline-require-approval:
388
James E. Blair5bf78a32015-07-30 18:08:24 +0000389 **approval**
James E. Blair11041d22014-05-02 14:49:53 -0700390 This requires that a certain kind of approval be present for the
391 current patchset of the change (the approval could be added by the
392 event in question). It takes several sub-parameters, all of which
393 are optional and are combined together so that there must be an
394 approval matching all specified requirements.
395
396 *username*
397 If present, an approval from this username is required.
398
James E. Blair1fbfceb2014-06-23 14:42:53 -0700399 *email*
James E. Blair11041d22014-05-02 14:49:53 -0700400 If present, an approval with this email address is required. It
401 is treated as a regular expression as above.
402
James E. Blair1fbfceb2014-06-23 14:42:53 -0700403 *email-filter* (deprecated)
404 A deprecated alternate spelling of *email*. Only one of *email* or
405 *email_filter* should be used.
406
James E. Blair11041d22014-05-02 14:49:53 -0700407 *older-than*
408 If present, the approval must be older than this amount of time
409 to match. Provide a time interval as a number with a suffix of
410 "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
411 (seconds). Example ``48h`` or ``2d``.
412
413 *newer-than*
414 If present, the approval must be newer than this amount of time
415 to match. Same format as "older-than".
416
417 Any other field is interpreted as a review category and value
418 pair. For example ``verified: 1`` would require that the approval
James E. Blair9c17dbf2014-06-23 14:21:58 -0700419 be for a +1 vote in the "Verified" column. The value may either
420 be a single value or a list: ``verified: [1, 2]`` would match
421 either a +1 or +2 vote.
James E. Blair11041d22014-05-02 14:49:53 -0700422
423 **open**
424 A boolean value (``true`` or ``false``) that indicates whether the change
425 must be open or closed in order to be enqueued.
426
Clark Boylana9702ad2014-05-08 17:17:24 -0700427 **current-patchset**
428 A boolean value (``true`` or ``false``) that indicates whether the change
429 must be the current patchset in order to be enqueued.
430
James E. Blair11041d22014-05-02 14:49:53 -0700431 **status**
432 A string value that corresponds with the status of the change
433 reported by the trigger. For example, when using the Gerrit
434 trigger, status values such as ``NEW`` or ``MERGED`` may be useful.
James E. Blair63bb0ef2013-07-29 17:14:51 -0700435
Joshua Hesketh66c8e522014-06-26 15:30:08 +1000436**reject**
437 If this section is present, it establishes pre-requisites that can
438 block an item from being enqueued. It can be considered a negative
439 version of **require**.
440
441 **approval**
442 This takes a list of approvals. If an approval matches the provided
443 criteria the change can not be entered into the pipeline. It follows
444 the same syntax as the :ref:`"require approval" pipeline above
445 <pipeline-require-approval>`.
446
447 Example to reject a change with any negative vote::
448
449 reject:
450 approval:
451 - code-review: [-1, -2]
452
James E. Blair2fa50962013-01-30 21:50:41 -0800453**dequeue-on-new-patchset**
454 Normally, if a new patchset is uploaded to a change that is in a
455 pipeline, the existing entry in the pipeline will be removed (with
456 jobs canceled and any dependent changes that can no longer merge as
457 well. To suppress this behavior (and allow jobs to continue
458 running), set this to ``false``. Default: ``true``.
459
James E. Blair17dd6772015-02-09 14:45:18 -0800460**ignore-dependencies**
461 In any kind of pipeline (dependent or independent), Zuul will
462 attempt to enqueue all dependencies ahead of the current change so
463 that they are tested together (independent pipelines report the
464 results of each change regardless of the results of changes ahead).
465 To ignore dependencies completely in an independent pipeline, set
466 this to ``true``. This option is ignored by dependent pipelines.
467 The default is: ``false``.
468
James E. Blaircdd00072012-06-08 19:17:28 -0700469**success**
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000470 Describes where Zuul should report to if all the jobs complete
471 successfully.
James E. Blaircdd00072012-06-08 19:17:28 -0700472 This section is optional; if it is omitted, Zuul will run jobs and
473 do nothing on success; it will not even report a message to Gerrit.
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000474 If the section is present, the listed reporter plugins will be
475 asked to report on the jobs.
Joshua Heskethfe485c62015-08-11 23:42:34 +1000476 The reporters are listed by their connection name. The options
477 available depend on the driver for the supplied connection.
478 See :doc:`reporters` for more details.
James E. Blaircdd00072012-06-08 19:17:28 -0700479
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400480**failure**
James E. Blaircdd00072012-06-08 19:17:28 -0700481 Uses the same syntax as **success**, but describes what Zuul should
482 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700483
Joshua Heskethb7179772014-01-30 23:30:46 +1100484**merge-failure**
485 Uses the same syntax as **success**, but describes what Zuul should
486 do if it is unable to merge in the patchset. If no merge-failure
487 reporters are listed then the ``failure`` reporters will be used to
488 notify of unsuccessful merges.
489
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400490**start**
James E. Blairdc253862012-06-13 17:12:42 -0700491 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700492 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700493 for example, to reset the value of the Verified review category.
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400494
Joshua Hesketh89e829d2015-02-10 16:29:45 +1100495**disabled**
496 Uses the same syntax as **success**, but describes what Zuul should
497 do when a pipeline is disabled.
498 See ``disable-after-consecutive-failures``.
499
500**disable-after-consecutive-failures**
501 If set, a pipeline can enter a ''disabled'' state if too many changes
502 in a row fail. When this value is exceeded the pipeline will stop
503 reporting to any of the ``success``, ``failure`` or ``merge-failure``
504 reporters and instead only report to the ``disabled`` reporters.
505 (No ``start`` reports are made when a pipeline is disabled).
506
James E. Blair64ed6f22013-07-10 14:07:23 -0700507**precedence**
508 Indicates how the build scheduler should prioritize jobs for
509 different pipelines. Each pipeline may have one precedence, jobs
510 for pipelines with a higher precedence will be run before ones with
511 lower. The value should be one of ``high``, ``normal``, or ``low``.
512 Default: ``normal``.
513
Clark Boylanc2d19e42014-01-23 14:08:58 -0800514**window**
515 DependentPipelineManagers only. Zuul can rate limit
516 DependentPipelineManagers in a manner similar to TCP flow control.
517 Jobs are only started for changes in the queue if they sit in the
518 actionable window for the pipeline. The initial length of this window
519 is configurable with this value. The value given should be a positive
520 integer value. A value of ``0`` disables rate limiting on the
521 DependentPipelineManager.
522 Default: ``20``.
523
524**window-floor**
525 DependentPipelineManagers only. This is the minimum value for the
526 window described above. Should be a positive non zero integer value.
527 Default: ``3``.
528
529**window-increase-type**
530 DependentPipelineManagers only. This value describes how the window
531 should grow when changes are successfully merged by zuul. A value of
532 ``linear`` indicates that ``window-increase-factor`` should be added
533 to the previous window value. A value of ``exponential`` indicates
534 that ``window-increase-factor`` should be multiplied against the
535 previous window value and the result will become the window size.
536 Default: ``linear``.
537
538**window-increase-factor**
Clint Adams041ae512015-06-16 20:02:29 -0400539 DependentPipelineManagers only. The value to be added or multiplied
Clark Boylanc2d19e42014-01-23 14:08:58 -0800540 against the previous window value to determine the new window after
541 successful change merges.
542 Default: ``1``.
543
544**window-decrease-type**
545 DependentPipelineManagers only. This value describes how the window
546 should shrink when changes are not able to be merged by Zuul. A value
547 of ``linear`` indicates that ``window-decrease-factor`` should be
548 subtracted from the previous window value. A value of ``exponential``
549 indicates that ``window-decrease-factor`` should be divided against
550 the previous window value and the result will become the window size.
551 Default: ``exponential``.
552
553**window-decrease-factor**
554 DependentPipelineManagers only. The value to be subtracted or divided
555 against the previous window value to determine the new window after
556 unsuccessful change merges.
557 Default: ``2``.
558
Clark Boylan00635dc2012-09-19 14:03:08 -0700559Some example pipeline configurations are included in the sample layout
560file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700561
562 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700563 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700564 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000565 my_gerrit:
566 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700567 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000568 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000569 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700570 failure:
Thomas Bechtolda8c0dbd2015-12-10 07:16:54 +0100571 my_gerrit:
572 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700573
574This will trigger jobs each time a new patchset (or change) is
575uploaded to Gerrit, and report +/-1 values to Gerrit in the
576``verified`` review category. ::
577
578 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700579 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700580 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000581 my_gerrit:
582 - event: comment-added
583 approval:
584 - approved: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700585 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000586 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000587 verified: 2
588 submit: true
James E. Blaircdd00072012-06-08 19:17:28 -0700589 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000590 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000591 verified: -2
James E. Blaircdd00072012-06-08 19:17:28 -0700592
593This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
594``approved`` review category in Gerrit (a non-standard category).
595Changes will be tested in such a way as to guarantee that they will be
596merged exactly as tested, though that will happen in parallel by
597creating a virtual queue of dependent changes and performing
598speculative execution of jobs. ::
599
600 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700601 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700602 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000603 my_gerrit:
604 - event: ref-updated
605 ref: ^(?!refs/).*$
James E. Blaircdd00072012-06-08 19:17:28 -0700606
607This will trigger jobs whenever a change is merged to a named branch
608(e.g., ``master``). No output will be reported to Gerrit. This is
609useful for side effects such as creating per-commit tarballs. ::
610
611 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700612 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700613 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000614 my_gerrit:
615 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700616
617This also triggers jobs when changes are uploaded to Gerrit, but no
618results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200619development and not yet ready to be presented to developers. ::
620
621 pipelines:
622 - name: post-merge
623 manager: IndependentPipelineManager
624 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000625 my_gerrit:
626 - event: change-merged
Antoine Mussoce333842012-10-16 14:42:35 +0200627 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000628 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000629 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200630 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000631 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000632 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200633
634The ``change-merged`` events happen when a change has been merged in the git
635repository. The change is thus closed and Gerrit will not accept modifications
636to the review scoring such as ``code-review`` or ``verified``. By using the
637``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
638``gerrit review`` command, thus making sure the message is actually
639sent back to Gerrit regardless of approval scores.
640That kind of pipeline is nice to run regression or performance tests.
641
642.. note::
643 The ``change-merged`` event does not include the commit sha1 which can be
644 hazardous, it would let you report back to Gerrit though. If you were to
Michael Prokop526926a2013-10-24 16:16:57 +0200645 build a tarball for a specific commit, you should consider instead using
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100646 the ``ref-updated`` event which does include the commit sha1 (but lacks the
Antoine Mussoce333842012-10-16 14:42:35 +0200647 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700648
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100649
650.. _jobs:
651
James E. Blaircdd00072012-06-08 19:17:28 -0700652Jobs
653""""
654
655The jobs section is optional, and can be used to set attributes of
656jobs that are independent of their association with a project. For
657example, if a job should return a customized message on failure, that
658may be specified here. Otherwise, Zuul does not need to be told about
659each job as it builds a list from the project specification.
660
661**name**
662 The name of the job. This field is treated as a regular expression
663 and will be applied to each job that matches.
664
James E. Blairc8a1e052014-02-25 09:29:26 -0800665**queue-name (optional)**
666 Zuul will automatically combine projects that share a job into
667 shared change queues for dependent pipeline managers. In order to
668 report statistics about these queues, it is convenient for them to
669 have names. Zuul can automatically name change queues, however
670 these can grow quite long and are prone to changing as projects in
671 the queue change. If you assign a queue-name to a job, Zuul will
672 use that as the name for the shared change queue that contains that
673 job instead of the automatically generated one. It is an error for
674 a shared change queue to have more than one job with a queue-name if
675 they are not the same.
676
James E. Blaire5a847f2012-07-10 15:29:14 -0700677**failure-message (optional)**
678 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700679
James E. Blaire5a847f2012-07-10 15:29:14 -0700680**success-message (optional)**
681 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700682
James E. Blair6aea36d2012-12-17 13:03:24 -0800683**failure-pattern (optional)**
684 The URL that should be reported to Gerrit if the job fails.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700685 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800686 zuul.conf. May be supplied as a string pattern with substitutions
687 as described in url_pattern in :ref:`zuulconf`.
688
689**success-pattern (optional)**
690 The URL that should be reported to Gerrit if the job succeeds.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700691 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800692 zuul.conf. May be supplied as a string pattern with substitutions
693 as described in url_pattern in :ref:`zuulconf`.
694
James E. Blair222d4982012-07-16 09:31:19 -0700695**hold-following-changes (optional)**
696 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700697 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700698 succeeds before launching. If this is applied to a very short job
699 that can predict whether longer jobs will fail early, this can be
700 used to reduce the number of jobs that Zuul will launch and
701 ultimately have to cancel. In that case, a small amount of
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400702 parallelization of jobs is traded for more efficient use of testing
James E. Blair222d4982012-07-16 09:31:19 -0700703 resources. On the other hand, to apply this to a long running job
704 would largely defeat the parallelization of dependent change testing
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400705 that is the main feature of Zuul. Default: ``false``.
James E. Blair222d4982012-07-16 09:31:19 -0700706
James E. Blairaf17a972016-02-03 15:07:18 -0800707**mutex (optional)**
708 This is a string that names a mutex that should be observed by this
709 job. Only one build of any job that references the same named mutex
710 will be enqueued at a time. This applies across all pipelines.
711
James E. Blaire5a847f2012-07-10 15:29:14 -0700712**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700713 This job should only be run on matching branches. This field is
714 treated as a regular expression and multiple branches may be
715 listed.
716
James E. Blair70c71582013-03-06 08:50:50 -0800717**files (optional)**
718 This job should only be run if at least one of the files involved in
719 the change (added, deleted, or modified) matches at least one of the
720 file patterns listed here. This field is treated as a regular
721 expression and multiple expressions may be listed.
722
Maru Newby3fe5f852015-01-13 04:22:14 +0000723**skip-if (optional)**
724
725 This job should not be run if all the patterns specified by the
726 optional fields listed below match on their targets. When multiple
727 sets of parameters are provided, this job will be skipped if any set
728 matches. For example: ::
729
730 jobs:
731 - name: check-tempest-dsvm-neutron
732 skip-if:
733 - project: ^openstack/neutron$
734 branch: ^stable/juno$
735 all-files-match-any:
736 - ^neutron/tests/.*$
737 - ^tools/.*$
738 - all-files-match-any:
739 - ^doc/.*$
740 - ^.*\.rst$
741
742 With this configuration, the job would be skipped for a neutron
743 patchset for the stable/juno branch provided that every file in the
744 change matched at least one of the specified file regexes. The job
745 will also be skipped for any patchset that modified only the doc
746 tree or rst files.
747
748 *project* (optional)
749 The regular expression to match against the project of the change.
750
751 *branch* (optional)
752 The regular expression to match against the branch or ref of the
753 change.
754
755 *all-files-match-any* (optional)
756 A list of regular expressions intended to match the files involved
757 in the change. This parameter will be considered matching a
758 change only if all files in a change match at least one of these
759 expressions.
760
761 The pattern for '/COMMIT_MSG' is always matched on and does not
762 have to be included.
763
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400764**voting (optional)**
765 Boolean value (``true`` or ``false``) that indicates whatever
766 a job is voting or not. Default: ``true``.
767
James E. Blair456f2fb2016-02-09 09:29:33 -0800768**tags (optional)**
769 A list of arbitrary strings which will be associated with the job.
770 Can be used by the parameter-function to alter behavior based on
771 their presence on a job. If the job name is a regular expression,
772 tags will accumulate on jobs that match.
773
James E. Blaire5a847f2012-07-10 15:29:14 -0700774**parameter-function (optional)**
775 Specifies a function that should be applied to the parameters before
776 the job is launched. The function should be defined in a python file
777 included with the :ref:`includes` directive. The function
778 should have the following signature:
779
James E. Blaird0470972013-07-29 10:05:43 -0700780 .. function:: parameters(item, job, parameters)
James E. Blaire5a847f2012-07-10 15:29:14 -0700781
782 Manipulate the parameters passed to a job before a build is
783 launched. The ``parameters`` dictionary will already contain the
784 standard Zuul job parameters, and is expected to be modified
785 in-place.
786
James E. Blaird78576a2013-07-09 10:39:17 -0700787 :param item: the current queue item
788 :type item: zuul.model.QueueItem
James E. Blaird0470972013-07-29 10:05:43 -0700789 :param job: the job about to be run
790 :type job: zuul.model.Job
James E. Blaire5a847f2012-07-10 15:29:14 -0700791 :param parameters: parameters to be passed to the job
792 :type parameters: dict
793
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700794 If the parameter **ZUUL_NODE** is set by this function, then it will
795 be used to specify on what node (or class of node) the job should be
796 run.
797
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100798**swift**
799 If :ref:`swift` is configured then each job can define a destination
800 container for the builder to place logs and/or assets into. Multiple
801 containers can be listed for each job by providing a unique ``name``.
802
803 *name*
804 Set an identifying name for the container. This is used in the
805 parameter key sent to the builder. For example if it ``logs`` then
806 one of the parameters sent will be ``SWIFT_logs_CONTAINER``
807 (case-sensitive).
808
809 Each of the defaults defined in :ref:`swift` can be overwritten as:
810
811 *container* (optional)
812 Container name to place the log into
813 ``For example, logs``
814
815 *expiry* (optional)
816 How long the signed destination should be available for
817
James E. Blaird6500232014-06-23 15:05:48 -0700818 *max-file-size** (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100819 The maximum size of an individual file
820
James E. Blaird6500232014-06-23 15:05:48 -0700821 *max_file_size** (optional, deprecated)
822 A deprecated alternate spelling of *max-file-size*.
823
824 *max-file-count* (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100825 The maximum number of separate files to allow
826
James E. Blaird6500232014-06-23 15:05:48 -0700827 *max_file_count* (optional, deprecated)
828 A deprecated alternate spelling of *max-file-count*.
829
830 *logserver-prefix*
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100831 Provide a URL to the CDN or logserver app so that a worker knows
832 what URL to return.
833 ``For example: http://logs.example.org/server.app?obj=``
James E. Blaird6500232014-06-23 15:05:48 -0700834 The worker should return the logserver-prefix url and the object
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100835 path as the URL in the results data packet.
836
James E. Blaird6500232014-06-23 15:05:48 -0700837 *logserver_prefix* (deprecated)
838 A deprecated alternate spelling of *logserver-prefix*.
839
James E. Blaircdd00072012-06-08 19:17:28 -0700840Here is an example of setting the failure message for jobs that check
841whether a change merges cleanly::
842
843 - name: ^.*-merge$
Jeremy Stanley1c2c3c22015-06-15 21:23:19 +0000844 failure-message: This change or one of its cross-repo dependencies
845 was unable to be automatically merged with the current state of
846 its repository. Please rebase the change and upload a new
847 patchset.
James E. Blaircdd00072012-06-08 19:17:28 -0700848
849Projects
850""""""""
851
Clark Boylan00635dc2012-09-19 14:03:08 -0700852The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700853for events associated with each project. It contains a list of
854projects. Here is an example::
855
856 - name: example/project
857 check:
858 - project-merge:
859 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700860 - project-pep8
861 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700862 gate:
863 - project-merge:
864 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700865 - project-pep8
866 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700867 post:
868 - project-publish
869
870**name**
871 The name of the project (as known by Gerrit).
872
James E. Blair19deff22013-08-25 13:17:35 -0700873**merge-mode (optional)**
874 An optional value that indicates what strategy should be used to
875 merge changes to this project. Supported values are:
876
877 ** merge-resolve **
878 Equivalent to 'git merge -s resolve'. This corresponds closely to
879 what Gerrit performs (using JGit) for a project if the "Merge if
880 necessary" merge mode is selected and "Automatically resolve
881 conflicts" is checked. This is the default.
882
883 ** merge **
884 Equivalent to 'git merge'.
885
886 ** cherry-pick **
887 Equivalent to 'git cherry-pick'.
888
Clark Boylan00635dc2012-09-19 14:03:08 -0700889This is followed by a section for each of the pipelines defined above.
890Pipelines may be omitted if no jobs should run for this project in a
891given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700892executed are listed. If a job is entered as a dictionary key, then
893jobs contained within that key are only executed if the key job
894succeeds. In the above example, project-unittest, project-pep8, and
895project-pyflakes are only executed if project-merge succeeds. This
896can help avoid running unnecessary jobs.
897
James E. Blair18c64442014-03-18 10:14:45 -0700898The special job named ``noop`` is internal to Zuul and will always
899return ``SUCCESS`` immediately. This can be useful if you require
900that all changes be processed by a pipeline but a project has no jobs
901that can be run on it.
902
Andreas Jaegerbcfbf932014-09-29 20:21:44 +0200903.. seealso:: The OpenStack Zuul configuration for a comprehensive example: https://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul/layout.yaml
James E. Blaircdd00072012-06-08 19:17:28 -0700904
Antoine Musso80edd5a2013-02-13 15:37:53 +0100905Project Templates
906"""""""""""""""""
907
Michael Prokop526926a2013-10-24 16:16:57 +0200908Whenever you have lot of similar projects (such as plugins for a project) you
Antoine Musso80edd5a2013-02-13 15:37:53 +0100909will most probably want to use the same pipeline configurations. The
910project templates let you define pipelines and job name templates to trigger.
911One can then just apply the template on its project which make it easier to
Michael Prokop526926a2013-10-24 16:16:57 +0200912update several similar projects. As an example::
Antoine Musso80edd5a2013-02-13 15:37:53 +0100913
914 project-templates:
915 # Name of the template
916 - name: plugin-triggering
917 # Definition of pipelines just like for a `project`
918 check:
919 - '{jobprefix}-merge':
920 - '{jobprefix}-pep8'
921 - '{jobprefix}-pyflakes'
922 gate:
923 - '{jobprefix}-merge':
924 - '{jobprefix}-unittest'
925 - '{jobprefix}-pep8'
926 - '{jobprefix}-pyflakes'
927
928In your projects definition, you will then apply the template using the template
929key::
930
931 projects:
932 - name: plugin/foobar
933 template:
934 - name: plugin-triggering
935 jobprefix: plugin-foobar
936
James E. Blairaea6cf62013-12-16 15:38:12 -0800937You can pass several parameters to a template. A ``parameter`` value
938will be used for expansion of ``{parameter}`` in the template
939strings. The parameter ``name`` will be automatically provided and
940will contain the short name of the project, that is the portion of the
941project name after the last ``/`` character.
James E. Blaircdd00072012-06-08 19:17:28 -0700942
James E. Blair3e98c022013-12-16 15:25:38 -0800943Multiple templates can be combined in a project, and the jobs from all
944of those templates will be added to the project. Individual jobs may
945also be added::
946
947 projects:
948 - name: plugin/foobar
949 template:
950 - name: plugin-triggering
951 jobprefix: plugin-foobar
952 - name: plugin-extras
953 jobprefix: plugin-foobar
954 check:
955 - foobar-extra-special-job
956
Steven Dake21ef9ad2014-08-25 23:08:14 -0700957Individual jobs may optionally be added to pipelines (e.g. check,
Atsushi SAKAI5d7e93b2015-07-28 22:15:48 +0900958gate, et cetera) for a project, in addition to those provided by
Steven Dake21ef9ad2014-08-25 23:08:14 -0700959templates.
960
James E. Blair3e98c022013-12-16 15:25:38 -0800961The order of the jobs listed in the project (which only affects the
962order of jobs listed on the report) will be the jobs from each
963template in the order listed, followed by any jobs individually listed
964for the project.
965
966Note that if multiple templates are used for a project and one
967template specifies a job that is also specified in another template,
James E. Blair12a92b12014-03-26 11:54:53 -0700968or specified in the project itself, the configuration defined by
969either the last template or the project itself will take priority.
James E. Blair3e98c022013-12-16 15:25:38 -0800970
James E. Blaircdd00072012-06-08 19:17:28 -0700971logging.conf
972~~~~~~~~~~~~
973This file is optional. If provided, it should be a standard
974:mod:`logging.config` module configuration file. If not present, Zuul will
975output all log messages of DEBUG level or higher to the console.
976
977Starting Zuul
978-------------
979
980To start Zuul, run **zuul-server**::
981
Antoine Mussob3aa8282013-04-19 15:16:59 +0200982 usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]
James E. Blaircdd00072012-06-08 19:17:28 -0700983
984 Project gating system.
985
986 optional arguments:
987 -h, --help show this help message and exit
988 -c CONFIG specify the config file
Antoine Mussob3aa8282013-04-19 15:16:59 +0200989 -l LAYOUT specify the layout file
James E. Blaircdd00072012-06-08 19:17:28 -0700990 -d do not run as a daemon
Antoine Mussob3aa8282013-04-19 15:16:59 +0200991 -t validate layout file syntax
992 --version show zuul version
James E. Blaircdd00072012-06-08 19:17:28 -0700993
994You may want to use the ``-d`` argument while you are initially setting
995up Zuul so you can detect any configuration errors quickly. Under
996normal operation, omit ``-d`` and let Zuul run as a daemon.
997
998If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
999stop executing new jobs, wait until all executing jobs are finished,
Joshua Heskethc4997152016-02-17 21:04:18 +11001000reload its layout.yaml, and resume. Changes to any connections or
1001the PID file will be ignored until Zuul is restarted.
Clark Boylanf231fa22013-02-08 12:28:53 -08001002
1003If you send a SIGUSR1 to the zuul-server process, Zuul will stop
1004executing new jobs, wait until all executing jobs are finished,
1005then exit. While waiting to exit Zuul will queue Gerrit events and
1006save these events prior to exiting. When Zuul starts again it will
1007read these saved events and act on them.
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001008
Michael Prokop526926a2013-10-24 16:16:57 +02001009If you need to abort Zuul and intend to manually requeue changes for
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001010jobs which were running in its pipelines, prior to terminating you can
1011use the zuul-changes.py tool script to simplify the process. For
Ramy Asselindda8e6a2015-03-31 14:59:39 -07001012example, this would give you a list of zuul-enqueue commands to requeue
1013changes for the gate and check pipelines respectively::
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001014
Ramy Asselindda8e6a2015-03-31 14:59:39 -07001015 ./tools/zuul-changes.py http://zuul.openstack.org/ gate
1016 ./tools/zuul-changes.py http://zuul.openstack.org/ check
Clark Boylanfba9b242013-08-20 10:11:17 -07001017
Antoine Musso29eab012014-10-28 21:35:22 +01001018If you send a SIGUSR2 to the zuul-server process, or the forked process
1019that runs the Gearman daemon, Zuul will dump a stack trace for each
1020running thread into its debug log. It is written under the log bucket
1021``zuul.stack_dump``. This is useful for tracking down deadlock or
1022otherwise slow threads.
Antoine Mussod0f06262014-06-04 09:54:24 +02001023
1024When `yappi <https://code.google.com/p/yappi/>`_ (Yet Another Python
1025Profiler) is available, additional functions' and threads' stats are
1026emitted as well. The first SIGUSR2 will enable yappi, on the second
1027SIGUSR2 it dumps the information collected, resets all yappi state and
1028stops profiling. This is to minimize the impact of yappi on a running
1029system.