blob: ad6a0611974bef065a96a66fcdbb1a3a2c7ced03 [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
Thanh Ha266cbb82016-01-24 20:57:59 -050013 other config files. (required)
James E. Blaircdd00072012-06-08 19:17:28 -070014**layout.yaml**
Thanh Ha266cbb82016-01-24 20:57:59 -050015 Project and pipeline configuration -- what Zuul does. (required)
James E. Blaircdd00072012-06-08 19:17:28 -070016**logging.conf**
Thanh Ha266cbb82016-01-24 20:57:59 -050017 Python logging config. (optional)
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
Thanh Ha266cbb82016-01-24 20:57:59 -050044Client connection information for gearman. If using Zuul's builtin gearmand
45server just set **server** to 127.0.0.1.
46
Clark Boylan9b670902012-09-28 13:47:56 -070047**server**
James E. Blair1f4c2bb2013-04-26 08:40:46 -070048 Hostname or IP address of the Gearman server.
Thanh Ha266cbb82016-01-24 20:57:59 -050049 ``server=gearman.example.com`` (required)
Clark Boylan9b670902012-09-28 13:47:56 -070050
James E. Blair1f4c2bb2013-04-26 08:40:46 -070051**port**
Łukasz Jernaś048acb42014-03-02 18:49:41 +010052 Port on which the Gearman server is listening.
Thanh Ha266cbb82016-01-24 20:57:59 -050053 ``port=4730`` (optional)
Clark Boylan9b670902012-09-28 13:47:56 -070054
James E. Blair77cc7b82013-07-15 13:22:37 -070055gearman_server
56""""""""""""""
57
Thanh Ha266cbb82016-01-24 20:57:59 -050058The builtin gearman server. Zuul can fork a gearman process from itself rather
59than connecting to an external one.
60
James E. Blair77cc7b82013-07-15 13:22:37 -070061**start**
62 Whether to start the internal Gearman server (default: False).
63 ``start=true``
64
James E. Blair0ac452e2015-07-22 09:05:16 -070065**listen_address**
66 IP address or domain name on which to listen (default: all addresses).
67 ``listen_address=127.0.0.1``
68
James E. Blair77cc7b82013-07-15 13:22:37 -070069**log_config**
70 Path to log config file for internal Gearman server.
71 ``log_config=/etc/zuul/gearman-logging.yaml``
72
Paul Belanger88ef0ea2015-12-23 11:57:02 -050073webapp
74""""""
75
76**listen_address**
77 IP address or domain name on which to listen (default: 0.0.0.0).
78 ``listen_address=127.0.0.1``
79
80**port**
81 Port on which the webapp is listening (default: 8001).
82 ``port=8008``
83
Clark Boylan9b670902012-09-28 13:47:56 -070084zuul
85""""
86
Thanh Ha266cbb82016-01-24 20:57:59 -050087Zuul's main configuration section. At minimum zuul must be able to find
88layout.yaml to be useful.
89
90.. note:: Must be provided when running zuul-server
91
Antoine Musso9adc6d42014-11-14 15:37:48 +010092.. _layout_config:
93
Clark Boylan9b670902012-09-28 13:47:56 -070094**layout_config**
James E. Blair4076e2b2014-01-28 12:42:20 -080095 Path to layout config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070096 ``layout_config=/etc/zuul/layout.yaml``
97
98**log_config**
James E. Blaira4430132014-02-17 08:32:07 -080099 Path to log config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -0700100 ``log_config=/etc/zuul/logging.yaml``
101
102**pidfile**
James E. Blaira4430132014-02-17 08:32:07 -0800103 Path to PID lock file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -0700104 ``pidfile=/var/run/zuul/zuul.pid``
105
106**state_dir**
James E. Blair4076e2b2014-01-28 12:42:20 -0800107 Path to directory that Zuul should save state to. Used by all Zuul
108 commands.
Clark Boylan9b670902012-09-28 13:47:56 -0700109 ``state_dir=/var/lib/zuul``
110
James E. Blair4076e2b2014-01-28 12:42:20 -0800111**report_times**
112 Boolean value (``true`` or ``false``) that determines if Zuul should
113 include elapsed times for each job in the textual report. Used by
114 zuul-server only.
115 ``report_times=true``
116
117**status_url**
118 URL that will be posted in Zuul comments made to Gerrit changes when
119 starting jobs for a change. Used by zuul-server only.
120 ``status_url=https://zuul.example.com/status``
121
Clark Boylane0b4bdb2014-06-03 17:01:25 -0700122**status_expiry**
123 Zuul will cache the status.json file for this many seconds. This is an
124 optional value and ``1`` is used by default.
125 ``status_expiry=1``
126
James E. Blair4076e2b2014-01-28 12:42:20 -0800127**url_pattern**
128 If you are storing build logs external to the system that originally
129 ran jobs and wish to link to those logs when Zuul makes comments on
130 Gerrit changes for completed jobs this setting configures what the
131 URLs for those links should be. Used by zuul-server only.
132 ``http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}``
133
134**job_name_in_report**
135 Boolean value (``true`` or ``false``) that indicates whether the
136 job name should be included in the report (normally only the URL
137 is included). Defaults to ``false``. Used by zuul-server only.
138 ``job_name_in_report=true``
139
140merger
141""""""
142
Thanh Ha266cbb82016-01-24 20:57:59 -0500143The zuul-merger process configuration. Detailed documentation on this process
144can be found on the :doc:`merger` page.
145
146.. note:: Must be provided when running zuul-merger. Both services may share the
147 same configuration (and even host) or otherwise have an individual
148 zuul.conf.
149
Clark Boylan9b670902012-09-28 13:47:56 -0700150**git_dir**
151 Directory that Zuul should clone local git repositories to.
152 ``git_dir=/var/lib/zuul/git``
153
Paul Belangerb67aba12013-05-13 19:22:14 -0400154**git_user_email**
155 Optional: Value to pass to `git config user.email`.
156 ``git_user_email=zuul@example.com``
157
158**git_user_name**
159 Optional: Value to pass to `git config user.name`.
160 ``git_user_name=zuul``
161
Arx Cruzb1b010d2013-10-28 19:49:59 -0200162**zuul_url**
James E. Blair4076e2b2014-01-28 12:42:20 -0800163 URL of this merger's git repos, accessible to test workers. Usually
164 "http://zuul.example.com/p" or "http://zuul-merger01.example.com/p"
165 depending on whether the merger is co-located with the Zuul server.
Arx Cruzb1b010d2013-10-28 19:49:59 -0200166
James E. Blaira4430132014-02-17 08:32:07 -0800167**log_config**
168 Path to log config file for the merger process.
169 ``log_config=/etc/zuul/logging.yaml``
170
171**pidfile**
172 Path to PID lock file for the merger process.
173 ``pidfile=/var/run/zuul-merger/merger.pid``
174
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100175.. _swift:
176
177swift
178"""""
179
180To send (optional) swift upload instructions this section must be
Antoine Musso62fa2d42014-06-04 22:55:23 +0200181present. Multiple destinations can be defined in the :ref:`jobs` section
182of the layout.
183
184If you are sending the temp-url-key or fetching the x-storage-url, you
185will need the python-swiftclient module installed.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100186
Joshua Heskethc4967502014-05-15 06:39:14 -0700187**X-Account-Meta-Temp-Url-Key** (optional)
188 This is the key used to sign the HMAC message. If you do not set a
189 key Zuul will generate one automatically.
190
191**Send-Temp-Url-Key** (optional)
192 Zuul can send the X-Account-Meta-Temp-Url-Key to swift for you if
193 you have set up the appropriate credentials in ``authurl`` below.
194 This isn't necessary if you know and have set your
195 X-Account-Meta-Temp-Url-Key.
Antoine Musso62fa2d42014-06-04 22:55:23 +0200196 If set, Zuul requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700197 ``default: true``
198
199**X-Storage-Url** (optional)
200 The storage URL is the destination to upload files into. If you do
201 not set this the ``authurl`` credentials are used to fetch the url
Antoine Musso62fa2d42014-06-04 22:55:23 +0200202 from swift and Zuul will requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700203
204**authurl** (optional)
205 The (keystone) Auth URL for swift.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100206 ``For example, https://identity.api.rackspacecloud.com/v2.0/``
Joshua Heskethc4967502014-05-15 06:39:14 -0700207 This is required if you have Send-Temp-Url-Key set to ``True`` or
208 if you have not supplied the X-Storage-Url.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100209
210Any of the `swiftclient connection parameters`_ can also be defined
211here by the same name. Including the os_options by their key name (
212``for example tenant_id``)
213
214.. _swiftclient connection parameters: http://docs.openstack.org/developer/python-swiftclient/swiftclient.html#module-swiftclient.client
215
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100216**region_name** (optional)
217 The region name holding the swift container
218 ``For example, SYD``
219
220Each destination defined by the :ref:`jobs` will have the following
221default values that it may overwrite.
222
223**default_container** (optional)
224 Container name to place the log into
225 ``For example, logs``
226
227**default_expiry** (optional)
228 How long the signed destination should be available for
229 ``default: 7200 (2hrs)``
230
231**default_max_file_size** (optional)
232 The maximum size of an individual file
233 ``default: 104857600 (100MB)``
234
235**default_max_file_count** (optional)
236 The maximum number of separate files to allow
237 ``default: 10``
238
239**default_logserver_prefix**
240 Provide a URL to the CDN or logserver app so that a worker knows
241 what URL to return. The worker should return the logserver_prefix
242 url and the object path.
243 ``For example: http://logs.example.org/server.app?obj=``
244
Joshua Heskethfe485c62015-08-11 23:42:34 +1000245.. _connection:
246
247connection ArbitraryName
248""""""""""""""""""""""""
249
250A connection can be listed with any arbitrary name. The required
251parameters are specified in the :ref:`connections` documentation
252depending on what driver you are using.
253
254.. _layoutyaml:
255
James E. Blaircdd00072012-06-08 19:17:28 -0700256layout.yaml
257~~~~~~~~~~~
258
Clark Boylan00635dc2012-09-19 14:03:08 -0700259This is the main configuration file for Zuul, where all of the pipelines
James E. Blaircdd00072012-06-08 19:17:28 -0700260and projects are defined, what tests should be run, and what actions
Clark Boylan00635dc2012-09-19 14:03:08 -0700261Zuul should perform. There are three sections: pipelines, jobs, and
James E. Blaircdd00072012-06-08 19:17:28 -0700262projects.
263
Clark Boylan00635dc2012-09-19 14:03:08 -0700264Pipelines
265"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700266
Clark Boylan00635dc2012-09-19 14:03:08 -0700267Zuul can have any number of independent pipelines. Whenever a matching
268Gerrit event is found for a pipeline, that event is added to the
269pipeline, and the jobs specified for that pipeline are run. When all
270jobs specified for the pipeline that were triggered by an event are
271completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700272
Clark Boylan00635dc2012-09-19 14:03:08 -0700273There are no pre-defined pipelines in Zuul, rather you can define
274whatever pipelines you need in the layout file. This is a very flexible
275system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700276
Clark Boylan00635dc2012-09-19 14:03:08 -0700277Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700278explanation of each of the parameters::
279
280 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700281 manager: IndependentPipelineManager
Joshua Heskethfe485c62015-08-11 23:42:34 +1000282 source: my_gerrit
James E. Blaircdd00072012-06-08 19:17:28 -0700283 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000284 my_gerrit:
James E. Blair6c358e72013-07-29 17:06:47 -0700285 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700286 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000287 my_gerrit:
288 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700289 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000290 my_gerrit
291 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700292
293**name**
294 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700295 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700296
James E. Blair8dbd56a2012-12-22 10:55:10 -0800297**description**
298 This is an optional field that may be used to provide a textual
299 description of the pipeline.
300
James E. Blairc0dedf82014-08-06 09:37:52 -0700301**source**
Joshua Heskethfe485c62015-08-11 23:42:34 +1000302 A required field that specifies a connection that provides access to
303 the change objects that this pipeline operates on. The name of the
304 connection as per the zuul.conf should be specified. The driver used
305 for the connection named will be the source. Currently only ``gerrit``
306 drivers are supported.
James E. Blairc0dedf82014-08-06 09:37:52 -0700307
James E. Blair56370192013-01-14 15:47:28 -0800308**success-message**
309 An optional field that supplies the introductory text in message
310 reported back to Gerrit when all the voting builds are successful.
311 Defaults to "Build successful."
312
313**failure-message**
314 An optional field that supplies the introductory text in message
315 reported back to Gerrit when at least one voting build fails.
316 Defaults to "Build failed."
317
Joshua Heskethb7179772014-01-30 23:30:46 +1100318**merge-failure-message**
319 An optional field that supplies the introductory text in message
320 reported back to Gerrit when a change fails to merge with the
321 current state of the repository.
322 Defaults to "Merge failed."
323
Joshua Hesketh3979e3e2014-03-04 11:21:10 +1100324**footer-message**
325 An optional field to supply additional information after test results.
326 Useful for adding information about the CI system such as debugging
327 and contact details.
328
James E. Blaircdd00072012-06-08 19:17:28 -0700329**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700330 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700331
Clark Boylan00635dc2012-09-19 14:03:08 -0700332 *IndependentPipelineManager*
333 Every event in this pipeline should be treated as independent of
334 other events in the pipeline. This is appropriate when the order of
335 events in the pipeline doesn't matter because the results of the
336 actions this pipeline performs can not affect other events in the
337 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700338 you may want to run tests on that change to provide early feedback
339 to reviewers. At the end of the tests, the change is not going to
340 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700341 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700342
Clark Boylan00635dc2012-09-19 14:03:08 -0700343 Another type of pipeline that is independent is a post-merge
344 pipeline. In that case, the changes have already merged, so the
345 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700346
Clark Boylan00635dc2012-09-19 14:03:08 -0700347 *DependentPipelineManager*
348 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700349 that every change is tested exactly as it is going to be merged
350 into the repository. An ideal gating system would test one change
351 at a time, applied to the tip of the repository, and only if that
352 change passed tests would it be merged. Then the next change in
353 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700354 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700355 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700356 their entry into the pipeline. It begins testing all changes in
357 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700358 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700359 merged in parallel. If a change near the front of the pipeline
360 fails its tests, each change behind it ignores whatever tests have
361 been completed and are tested again without the change in front.
362 This way gate tests may run in parallel but still be tested
363 correctly, exactly as they will appear in the repository when
364 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700365
Clark Boylan00635dc2012-09-19 14:03:08 -0700366 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700367 it analyzes the jobs that are triggered by different projects, and
368 if those projects have jobs in common, it treats those projects as
369 related, and they share a single virtual queue of changes. Thus,
370 if there is a job that performs integration testing on two
371 projects, those two projects will automatically share a virtual
372 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700373 will be part of a separate virtual change queue, and changes to
374 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700375
376 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700377 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700378
379**trigger**
James E. Blairc494d542014-08-06 09:23:52 -0700380 At least one trigger source must be supplied for each pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700381 Triggers are not exclusive -- matching events may be placed in
James E. Blair6c358e72013-07-29 17:06:47 -0700382 multiple pipelines, and they will behave independently in each of
Joshua Heskethfe485c62015-08-11 23:42:34 +1000383 the pipelines they match.
James E. Blaircdd00072012-06-08 19:17:28 -0700384
Joshua Heskethfe485c62015-08-11 23:42:34 +1000385 Triggers are loaded from their connection name. The driver type of
386 the connection will dictate which options are available.
387 See :doc:`triggers`.
James E. Blairc494d542014-08-06 09:23:52 -0700388
James E. Blair11041d22014-05-02 14:49:53 -0700389**require**
390 If this section is present, it established pre-requisites for any
391 kind of item entering the Pipeline. Regardless of how the item is
392 to be enqueued (via any trigger or automatic dependency resolution),
393 the conditions specified here must be met or the item will not be
394 enqueued.
395
Antoine Musso27ab0d52014-10-22 14:20:17 +0200396.. _pipeline-require-approval:
397
James E. Blair5bf78a32015-07-30 18:08:24 +0000398 **approval**
James E. Blair11041d22014-05-02 14:49:53 -0700399 This requires that a certain kind of approval be present for the
400 current patchset of the change (the approval could be added by the
401 event in question). It takes several sub-parameters, all of which
402 are optional and are combined together so that there must be an
403 approval matching all specified requirements.
404
405 *username*
James E. Blairb01ec542016-06-16 09:46:49 -0700406 If present, an approval from this username is required. It is
407 treated as a regular expression.
James E. Blair11041d22014-05-02 14:49:53 -0700408
James E. Blair1fbfceb2014-06-23 14:42:53 -0700409 *email*
James E. Blair11041d22014-05-02 14:49:53 -0700410 If present, an approval with this email address is required. It
James E. Blairb01ec542016-06-16 09:46:49 -0700411 is treated as a regular expression.
James E. Blair11041d22014-05-02 14:49:53 -0700412
James E. Blair1fbfceb2014-06-23 14:42:53 -0700413 *email-filter* (deprecated)
414 A deprecated alternate spelling of *email*. Only one of *email* or
415 *email_filter* should be used.
416
James E. Blair11041d22014-05-02 14:49:53 -0700417 *older-than*
418 If present, the approval must be older than this amount of time
419 to match. Provide a time interval as a number with a suffix of
420 "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
421 (seconds). Example ``48h`` or ``2d``.
422
423 *newer-than*
424 If present, the approval must be newer than this amount of time
425 to match. Same format as "older-than".
426
427 Any other field is interpreted as a review category and value
428 pair. For example ``verified: 1`` would require that the approval
James E. Blair9c17dbf2014-06-23 14:21:58 -0700429 be for a +1 vote in the "Verified" column. The value may either
430 be a single value or a list: ``verified: [1, 2]`` would match
431 either a +1 or +2 vote.
James E. Blair11041d22014-05-02 14:49:53 -0700432
433 **open**
434 A boolean value (``true`` or ``false``) that indicates whether the change
435 must be open or closed in order to be enqueued.
436
Clark Boylana9702ad2014-05-08 17:17:24 -0700437 **current-patchset**
438 A boolean value (``true`` or ``false``) that indicates whether the change
439 must be the current patchset in order to be enqueued.
440
James E. Blair11041d22014-05-02 14:49:53 -0700441 **status**
442 A string value that corresponds with the status of the change
443 reported by the trigger. For example, when using the Gerrit
444 trigger, status values such as ``NEW`` or ``MERGED`` may be useful.
James E. Blair63bb0ef2013-07-29 17:14:51 -0700445
Joshua Hesketh66c8e522014-06-26 15:30:08 +1000446**reject**
447 If this section is present, it establishes pre-requisites that can
448 block an item from being enqueued. It can be considered a negative
449 version of **require**.
450
451 **approval**
452 This takes a list of approvals. If an approval matches the provided
453 criteria the change can not be entered into the pipeline. It follows
454 the same syntax as the :ref:`"require approval" pipeline above
455 <pipeline-require-approval>`.
456
457 Example to reject a change with any negative vote::
458
459 reject:
460 approval:
461 - code-review: [-1, -2]
462
James E. Blair2fa50962013-01-30 21:50:41 -0800463**dequeue-on-new-patchset**
464 Normally, if a new patchset is uploaded to a change that is in a
465 pipeline, the existing entry in the pipeline will be removed (with
466 jobs canceled and any dependent changes that can no longer merge as
467 well. To suppress this behavior (and allow jobs to continue
468 running), set this to ``false``. Default: ``true``.
469
James E. Blair17dd6772015-02-09 14:45:18 -0800470**ignore-dependencies**
471 In any kind of pipeline (dependent or independent), Zuul will
472 attempt to enqueue all dependencies ahead of the current change so
473 that they are tested together (independent pipelines report the
474 results of each change regardless of the results of changes ahead).
475 To ignore dependencies completely in an independent pipeline, set
476 this to ``true``. This option is ignored by dependent pipelines.
477 The default is: ``false``.
478
James E. Blaircdd00072012-06-08 19:17:28 -0700479**success**
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000480 Describes where Zuul should report to if all the jobs complete
481 successfully.
James E. Blaircdd00072012-06-08 19:17:28 -0700482 This section is optional; if it is omitted, Zuul will run jobs and
483 do nothing on success; it will not even report a message to Gerrit.
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000484 If the section is present, the listed reporter plugins will be
485 asked to report on the jobs.
Joshua Heskethfe485c62015-08-11 23:42:34 +1000486 The reporters are listed by their connection name. The options
487 available depend on the driver for the supplied connection.
488 See :doc:`reporters` for more details.
James E. Blaircdd00072012-06-08 19:17:28 -0700489
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400490**failure**
James E. Blaircdd00072012-06-08 19:17:28 -0700491 Uses the same syntax as **success**, but describes what Zuul should
492 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700493
Joshua Heskethb7179772014-01-30 23:30:46 +1100494**merge-failure**
495 Uses the same syntax as **success**, but describes what Zuul should
496 do if it is unable to merge in the patchset. If no merge-failure
497 reporters are listed then the ``failure`` reporters will be used to
498 notify of unsuccessful merges.
499
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400500**start**
James E. Blairdc253862012-06-13 17:12:42 -0700501 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700502 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700503 for example, to reset the value of the Verified review category.
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400504
Joshua Hesketh89e829d2015-02-10 16:29:45 +1100505**disabled**
506 Uses the same syntax as **success**, but describes what Zuul should
507 do when a pipeline is disabled.
508 See ``disable-after-consecutive-failures``.
509
510**disable-after-consecutive-failures**
511 If set, a pipeline can enter a ''disabled'' state if too many changes
512 in a row fail. When this value is exceeded the pipeline will stop
513 reporting to any of the ``success``, ``failure`` or ``merge-failure``
514 reporters and instead only report to the ``disabled`` reporters.
515 (No ``start`` reports are made when a pipeline is disabled).
516
James E. Blair64ed6f22013-07-10 14:07:23 -0700517**precedence**
518 Indicates how the build scheduler should prioritize jobs for
519 different pipelines. Each pipeline may have one precedence, jobs
520 for pipelines with a higher precedence will be run before ones with
521 lower. The value should be one of ``high``, ``normal``, or ``low``.
522 Default: ``normal``.
523
Clark Boylanc2d19e42014-01-23 14:08:58 -0800524**window**
525 DependentPipelineManagers only. Zuul can rate limit
526 DependentPipelineManagers in a manner similar to TCP flow control.
527 Jobs are only started for changes in the queue if they sit in the
528 actionable window for the pipeline. The initial length of this window
529 is configurable with this value. The value given should be a positive
530 integer value. A value of ``0`` disables rate limiting on the
531 DependentPipelineManager.
532 Default: ``20``.
533
534**window-floor**
535 DependentPipelineManagers only. This is the minimum value for the
536 window described above. Should be a positive non zero integer value.
537 Default: ``3``.
538
539**window-increase-type**
540 DependentPipelineManagers only. This value describes how the window
541 should grow when changes are successfully merged by zuul. A value of
542 ``linear`` indicates that ``window-increase-factor`` should be added
543 to the previous window value. A value of ``exponential`` indicates
544 that ``window-increase-factor`` should be multiplied against the
545 previous window value and the result will become the window size.
546 Default: ``linear``.
547
548**window-increase-factor**
Clint Adams041ae512015-06-16 20:02:29 -0400549 DependentPipelineManagers only. The value to be added or multiplied
Clark Boylanc2d19e42014-01-23 14:08:58 -0800550 against the previous window value to determine the new window after
551 successful change merges.
552 Default: ``1``.
553
554**window-decrease-type**
555 DependentPipelineManagers only. This value describes how the window
556 should shrink when changes are not able to be merged by Zuul. A value
557 of ``linear`` indicates that ``window-decrease-factor`` should be
558 subtracted from the previous window value. A value of ``exponential``
559 indicates that ``window-decrease-factor`` should be divided against
560 the previous window value and the result will become the window size.
561 Default: ``exponential``.
562
563**window-decrease-factor**
564 DependentPipelineManagers only. The value to be subtracted or divided
565 against the previous window value to determine the new window after
566 unsuccessful change merges.
567 Default: ``2``.
568
Clark Boylan00635dc2012-09-19 14:03:08 -0700569Some example pipeline configurations are included in the sample layout
570file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700571
572 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700573 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700574 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000575 my_gerrit:
576 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700577 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000578 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000579 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700580 failure:
Thomas Bechtolda8c0dbd2015-12-10 07:16:54 +0100581 my_gerrit:
582 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700583
584This will trigger jobs each time a new patchset (or change) is
585uploaded to Gerrit, and report +/-1 values to Gerrit in the
586``verified`` review category. ::
587
588 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700589 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700590 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000591 my_gerrit:
592 - event: comment-added
593 approval:
594 - approved: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700595 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000596 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000597 verified: 2
598 submit: true
James E. Blaircdd00072012-06-08 19:17:28 -0700599 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000600 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000601 verified: -2
James E. Blaircdd00072012-06-08 19:17:28 -0700602
603This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
604``approved`` review category in Gerrit (a non-standard category).
605Changes will be tested in such a way as to guarantee that they will be
606merged exactly as tested, though that will happen in parallel by
607creating a virtual queue of dependent changes and performing
608speculative execution of jobs. ::
609
610 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700611 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700612 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000613 my_gerrit:
614 - event: ref-updated
615 ref: ^(?!refs/).*$
James E. Blaircdd00072012-06-08 19:17:28 -0700616
617This will trigger jobs whenever a change is merged to a named branch
618(e.g., ``master``). No output will be reported to Gerrit. This is
619useful for side effects such as creating per-commit tarballs. ::
620
621 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700622 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700623 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000624 my_gerrit:
625 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700626
627This also triggers jobs when changes are uploaded to Gerrit, but no
628results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200629development and not yet ready to be presented to developers. ::
630
631 pipelines:
632 - name: post-merge
633 manager: IndependentPipelineManager
634 trigger:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000635 my_gerrit:
636 - event: change-merged
Antoine Mussoce333842012-10-16 14:42:35 +0200637 success:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000638 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000639 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200640 failure:
Joshua Heskethfe485c62015-08-11 23:42:34 +1000641 my_gerrit:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000642 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200643
644The ``change-merged`` events happen when a change has been merged in the git
645repository. The change is thus closed and Gerrit will not accept modifications
646to the review scoring such as ``code-review`` or ``verified``. By using the
647``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
648``gerrit review`` command, thus making sure the message is actually
649sent back to Gerrit regardless of approval scores.
650That kind of pipeline is nice to run regression or performance tests.
651
652.. note::
653 The ``change-merged`` event does not include the commit sha1 which can be
654 hazardous, it would let you report back to Gerrit though. If you were to
Michael Prokop526926a2013-10-24 16:16:57 +0200655 build a tarball for a specific commit, you should consider instead using
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100656 the ``ref-updated`` event which does include the commit sha1 (but lacks the
Antoine Mussoce333842012-10-16 14:42:35 +0200657 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700658
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100659
660.. _jobs:
661
James E. Blaircdd00072012-06-08 19:17:28 -0700662Jobs
663""""
664
665The jobs section is optional, and can be used to set attributes of
666jobs that are independent of their association with a project. For
667example, if a job should return a customized message on failure, that
668may be specified here. Otherwise, Zuul does not need to be told about
669each job as it builds a list from the project specification.
670
671**name**
672 The name of the job. This field is treated as a regular expression
673 and will be applied to each job that matches.
674
James E. Blairc8a1e052014-02-25 09:29:26 -0800675**queue-name (optional)**
676 Zuul will automatically combine projects that share a job into
677 shared change queues for dependent pipeline managers. In order to
678 report statistics about these queues, it is convenient for them to
679 have names. Zuul can automatically name change queues, however
680 these can grow quite long and are prone to changing as projects in
681 the queue change. If you assign a queue-name to a job, Zuul will
682 use that as the name for the shared change queue that contains that
683 job instead of the automatically generated one. It is an error for
684 a shared change queue to have more than one job with a queue-name if
685 they are not the same.
686
James E. Blaire5a847f2012-07-10 15:29:14 -0700687**failure-message (optional)**
688 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700689
James E. Blaire5a847f2012-07-10 15:29:14 -0700690**success-message (optional)**
691 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700692
James E. Blair6aea36d2012-12-17 13:03:24 -0800693**failure-pattern (optional)**
694 The URL that should be reported to Gerrit if the job fails.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700695 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800696 zuul.conf. May be supplied as a string pattern with substitutions
697 as described in url_pattern in :ref:`zuulconf`.
698
699**success-pattern (optional)**
700 The URL that should be reported to Gerrit if the job succeeds.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700701 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800702 zuul.conf. May be supplied as a string pattern with substitutions
703 as described in url_pattern in :ref:`zuulconf`.
704
James E. Blair222d4982012-07-16 09:31:19 -0700705**hold-following-changes (optional)**
706 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700707 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700708 succeeds before launching. If this is applied to a very short job
709 that can predict whether longer jobs will fail early, this can be
710 used to reduce the number of jobs that Zuul will launch and
711 ultimately have to cancel. In that case, a small amount of
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400712 parallelization of jobs is traded for more efficient use of testing
James E. Blair222d4982012-07-16 09:31:19 -0700713 resources. On the other hand, to apply this to a long running job
714 would largely defeat the parallelization of dependent change testing
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400715 that is the main feature of Zuul. Default: ``false``.
James E. Blair222d4982012-07-16 09:31:19 -0700716
James E. Blairaf17a972016-02-03 15:07:18 -0800717**mutex (optional)**
718 This is a string that names a mutex that should be observed by this
719 job. Only one build of any job that references the same named mutex
720 will be enqueued at a time. This applies across all pipelines.
721
James E. Blaire5a847f2012-07-10 15:29:14 -0700722**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700723 This job should only be run on matching branches. This field is
724 treated as a regular expression and multiple branches may be
725 listed.
726
James E. Blair70c71582013-03-06 08:50:50 -0800727**files (optional)**
728 This job should only be run if at least one of the files involved in
729 the change (added, deleted, or modified) matches at least one of the
730 file patterns listed here. This field is treated as a regular
731 expression and multiple expressions may be listed.
732
Maru Newby3fe5f852015-01-13 04:22:14 +0000733**skip-if (optional)**
734
735 This job should not be run if all the patterns specified by the
736 optional fields listed below match on their targets. When multiple
737 sets of parameters are provided, this job will be skipped if any set
738 matches. For example: ::
739
740 jobs:
741 - name: check-tempest-dsvm-neutron
742 skip-if:
743 - project: ^openstack/neutron$
744 branch: ^stable/juno$
745 all-files-match-any:
746 - ^neutron/tests/.*$
747 - ^tools/.*$
748 - all-files-match-any:
749 - ^doc/.*$
750 - ^.*\.rst$
751
752 With this configuration, the job would be skipped for a neutron
753 patchset for the stable/juno branch provided that every file in the
754 change matched at least one of the specified file regexes. The job
755 will also be skipped for any patchset that modified only the doc
756 tree or rst files.
757
758 *project* (optional)
759 The regular expression to match against the project of the change.
760
761 *branch* (optional)
762 The regular expression to match against the branch or ref of the
763 change.
764
765 *all-files-match-any* (optional)
766 A list of regular expressions intended to match the files involved
767 in the change. This parameter will be considered matching a
768 change only if all files in a change match at least one of these
769 expressions.
770
771 The pattern for '/COMMIT_MSG' is always matched on and does not
Alexander Evseevdbe6fab2015-11-19 12:46:34 +0300772 have to be included. Exception is merge commits (without modified
773 files), in this case '/COMMIT_MSG' is not matched, and job is not
774 skipped. In case of merge commits it's assumed that list of modified
775 files isn't predictible and CI should be run.
Maru Newby3fe5f852015-01-13 04:22:14 +0000776
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400777**voting (optional)**
778 Boolean value (``true`` or ``false``) that indicates whatever
779 a job is voting or not. Default: ``true``.
780
James E. Blair456f2fb2016-02-09 09:29:33 -0800781**tags (optional)**
782 A list of arbitrary strings which will be associated with the job.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700783
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100784**swift**
785 If :ref:`swift` is configured then each job can define a destination
786 container for the builder to place logs and/or assets into. Multiple
787 containers can be listed for each job by providing a unique ``name``.
788
789 *name*
790 Set an identifying name for the container. This is used in the
791 parameter key sent to the builder. For example if it ``logs`` then
792 one of the parameters sent will be ``SWIFT_logs_CONTAINER``
793 (case-sensitive).
794
795 Each of the defaults defined in :ref:`swift` can be overwritten as:
796
797 *container* (optional)
798 Container name to place the log into
799 ``For example, logs``
800
801 *expiry* (optional)
802 How long the signed destination should be available for
803
James E. Blaird6500232014-06-23 15:05:48 -0700804 *max-file-size** (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100805 The maximum size of an individual file
806
James E. Blaird6500232014-06-23 15:05:48 -0700807 *max_file_size** (optional, deprecated)
808 A deprecated alternate spelling of *max-file-size*.
809
810 *max-file-count* (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100811 The maximum number of separate files to allow
812
James E. Blaird6500232014-06-23 15:05:48 -0700813 *max_file_count* (optional, deprecated)
814 A deprecated alternate spelling of *max-file-count*.
815
816 *logserver-prefix*
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100817 Provide a URL to the CDN or logserver app so that a worker knows
818 what URL to return.
819 ``For example: http://logs.example.org/server.app?obj=``
James E. Blaird6500232014-06-23 15:05:48 -0700820 The worker should return the logserver-prefix url and the object
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100821 path as the URL in the results data packet.
822
James E. Blaird6500232014-06-23 15:05:48 -0700823 *logserver_prefix* (deprecated)
824 A deprecated alternate spelling of *logserver-prefix*.
825
James E. Blaircdd00072012-06-08 19:17:28 -0700826Here is an example of setting the failure message for jobs that check
827whether a change merges cleanly::
828
829 - name: ^.*-merge$
Jeremy Stanley1c2c3c22015-06-15 21:23:19 +0000830 failure-message: This change or one of its cross-repo dependencies
831 was unable to be automatically merged with the current state of
832 its repository. Please rebase the change and upload a new
833 patchset.
James E. Blaircdd00072012-06-08 19:17:28 -0700834
835Projects
836""""""""
837
Clark Boylan00635dc2012-09-19 14:03:08 -0700838The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700839for events associated with each project. It contains a list of
840projects. Here is an example::
841
842 - name: example/project
843 check:
844 - project-merge:
845 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700846 - project-pep8
847 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700848 gate:
849 - project-merge:
850 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700851 - project-pep8
852 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700853 post:
854 - project-publish
855
856**name**
857 The name of the project (as known by Gerrit).
858
James E. Blair19deff22013-08-25 13:17:35 -0700859**merge-mode (optional)**
860 An optional value that indicates what strategy should be used to
861 merge changes to this project. Supported values are:
862
863 ** merge-resolve **
864 Equivalent to 'git merge -s resolve'. This corresponds closely to
865 what Gerrit performs (using JGit) for a project if the "Merge if
866 necessary" merge mode is selected and "Automatically resolve
867 conflicts" is checked. This is the default.
868
869 ** merge **
870 Equivalent to 'git merge'.
871
872 ** cherry-pick **
873 Equivalent to 'git cherry-pick'.
874
Clark Boylan00635dc2012-09-19 14:03:08 -0700875This is followed by a section for each of the pipelines defined above.
876Pipelines may be omitted if no jobs should run for this project in a
877given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700878executed are listed. If a job is entered as a dictionary key, then
879jobs contained within that key are only executed if the key job
880succeeds. In the above example, project-unittest, project-pep8, and
881project-pyflakes are only executed if project-merge succeeds. This
882can help avoid running unnecessary jobs.
883
James E. Blair18c64442014-03-18 10:14:45 -0700884The special job named ``noop`` is internal to Zuul and will always
885return ``SUCCESS`` immediately. This can be useful if you require
886that all changes be processed by a pipeline but a project has no jobs
887that can be run on it.
888
Andreas Jaegerbcfbf932014-09-29 20:21:44 +0200889.. 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 -0700890
Antoine Musso80edd5a2013-02-13 15:37:53 +0100891Project Templates
892"""""""""""""""""
893
Michael Prokop526926a2013-10-24 16:16:57 +0200894Whenever you have lot of similar projects (such as plugins for a project) you
Antoine Musso80edd5a2013-02-13 15:37:53 +0100895will most probably want to use the same pipeline configurations. The
896project templates let you define pipelines and job name templates to trigger.
897One can then just apply the template on its project which make it easier to
Michael Prokop526926a2013-10-24 16:16:57 +0200898update several similar projects. As an example::
Antoine Musso80edd5a2013-02-13 15:37:53 +0100899
900 project-templates:
901 # Name of the template
902 - name: plugin-triggering
903 # Definition of pipelines just like for a `project`
904 check:
905 - '{jobprefix}-merge':
906 - '{jobprefix}-pep8'
907 - '{jobprefix}-pyflakes'
908 gate:
909 - '{jobprefix}-merge':
910 - '{jobprefix}-unittest'
911 - '{jobprefix}-pep8'
912 - '{jobprefix}-pyflakes'
913
914In your projects definition, you will then apply the template using the template
915key::
916
917 projects:
918 - name: plugin/foobar
919 template:
920 - name: plugin-triggering
921 jobprefix: plugin-foobar
922
James E. Blairaea6cf62013-12-16 15:38:12 -0800923You can pass several parameters to a template. A ``parameter`` value
924will be used for expansion of ``{parameter}`` in the template
925strings. The parameter ``name`` will be automatically provided and
926will contain the short name of the project, that is the portion of the
927project name after the last ``/`` character.
James E. Blaircdd00072012-06-08 19:17:28 -0700928
James E. Blair3e98c022013-12-16 15:25:38 -0800929Multiple templates can be combined in a project, and the jobs from all
930of those templates will be added to the project. Individual jobs may
931also be added::
932
933 projects:
934 - name: plugin/foobar
935 template:
936 - name: plugin-triggering
937 jobprefix: plugin-foobar
938 - name: plugin-extras
939 jobprefix: plugin-foobar
940 check:
941 - foobar-extra-special-job
942
Steven Dake21ef9ad2014-08-25 23:08:14 -0700943Individual jobs may optionally be added to pipelines (e.g. check,
Atsushi SAKAI5d7e93b2015-07-28 22:15:48 +0900944gate, et cetera) for a project, in addition to those provided by
Steven Dake21ef9ad2014-08-25 23:08:14 -0700945templates.
946
James E. Blair3e98c022013-12-16 15:25:38 -0800947The order of the jobs listed in the project (which only affects the
948order of jobs listed on the report) will be the jobs from each
949template in the order listed, followed by any jobs individually listed
950for the project.
951
952Note that if multiple templates are used for a project and one
953template specifies a job that is also specified in another template,
James E. Blair12a92b12014-03-26 11:54:53 -0700954or specified in the project itself, the configuration defined by
955either the last template or the project itself will take priority.
James E. Blair3e98c022013-12-16 15:25:38 -0800956
James E. Blaircdd00072012-06-08 19:17:28 -0700957logging.conf
958~~~~~~~~~~~~
959This file is optional. If provided, it should be a standard
960:mod:`logging.config` module configuration file. If not present, Zuul will
961output all log messages of DEBUG level or higher to the console.
962
963Starting Zuul
964-------------
965
966To start Zuul, run **zuul-server**::
967
Antoine Mussob3aa8282013-04-19 15:16:59 +0200968 usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]
James E. Blaircdd00072012-06-08 19:17:28 -0700969
970 Project gating system.
971
972 optional arguments:
973 -h, --help show this help message and exit
974 -c CONFIG specify the config file
Antoine Mussob3aa8282013-04-19 15:16:59 +0200975 -l LAYOUT specify the layout file
James E. Blaircdd00072012-06-08 19:17:28 -0700976 -d do not run as a daemon
Antoine Mussob3aa8282013-04-19 15:16:59 +0200977 -t validate layout file syntax
978 --version show zuul version
James E. Blaircdd00072012-06-08 19:17:28 -0700979
980You may want to use the ``-d`` argument while you are initially setting
981up Zuul so you can detect any configuration errors quickly. Under
982normal operation, omit ``-d`` and let Zuul run as a daemon.
983
984If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
985stop executing new jobs, wait until all executing jobs are finished,
Joshua Heskethc4997152016-02-17 21:04:18 +1100986reload its layout.yaml, and resume. Changes to any connections or
987the PID file will be ignored until Zuul is restarted.
Clark Boylanf231fa22013-02-08 12:28:53 -0800988
989If you send a SIGUSR1 to the zuul-server process, Zuul will stop
990executing new jobs, wait until all executing jobs are finished,
991then exit. While waiting to exit Zuul will queue Gerrit events and
992save these events prior to exiting. When Zuul starts again it will
993read these saved events and act on them.
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000994
Michael Prokop526926a2013-10-24 16:16:57 +0200995If you need to abort Zuul and intend to manually requeue changes for
Jeremy Stanley93e05f42013-03-08 17:29:17 +0000996jobs which were running in its pipelines, prior to terminating you can
997use the zuul-changes.py tool script to simplify the process. For
Ramy Asselindda8e6a2015-03-31 14:59:39 -0700998example, this would give you a list of zuul-enqueue commands to requeue
999changes for the gate and check pipelines respectively::
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001000
Ramy Asselindda8e6a2015-03-31 14:59:39 -07001001 ./tools/zuul-changes.py http://zuul.openstack.org/ gate
1002 ./tools/zuul-changes.py http://zuul.openstack.org/ check
Clark Boylanfba9b242013-08-20 10:11:17 -07001003
Antoine Musso29eab012014-10-28 21:35:22 +01001004If you send a SIGUSR2 to the zuul-server process, or the forked process
1005that runs the Gearman daemon, Zuul will dump a stack trace for each
1006running thread into its debug log. It is written under the log bucket
1007``zuul.stack_dump``. This is useful for tracking down deadlock or
1008otherwise slow threads.
Antoine Mussod0f06262014-06-04 09:54:24 +02001009
1010When `yappi <https://code.google.com/p/yappi/>`_ (Yet Another Python
1011Profiler) is available, additional functions' and threads' stats are
1012emitted as well. The first SIGUSR2 will enable yappi, on the second
1013SIGUSR2 it dumps the information collected, resets all yappi state and
1014stops profiling. This is to minimize the impact of yappi on a running
1015system.