blob: 6e9fb05a9301ca375edeab7540b80c9b7e0b2b1a [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
59**log_config**
60 Path to log config file for internal Gearman server.
61 ``log_config=/etc/zuul/gearman-logging.yaml``
62
Clark Boylan9b670902012-09-28 13:47:56 -070063gerrit
64""""""
65
66**server**
67 FQDN of Gerrit server.
68 ``server=review.example.com``
69
Akihiro Motokic7d28a72014-03-22 09:21:38 +090070**port**
71 Optional: Gerrit server port.
72 ``port=29418``
73
Antoine Musso27475012012-11-26 09:53:01 +010074**baseurl**
75 Optional: path to Gerrit web interface. Defaults to ``https://<value
76 of server>/``. ``baseurl=https://review.example.com/review_site/``
77
Clark Boylan9b670902012-09-28 13:47:56 -070078**user**
79 User name to use when logging into above server via ssh.
James E. Blair1f4c2bb2013-04-26 08:40:46 -070080 ``user=zuul``
Clark Boylan9b670902012-09-28 13:47:56 -070081
82**sshkey**
83 Path to SSH key to use when logging into above server.
James E. Blair1f4c2bb2013-04-26 08:40:46 -070084 ``sshkey=/home/zuul/.ssh/id_rsa``
Clark Boylan9b670902012-09-28 13:47:56 -070085
86zuul
87""""
88
Antoine Musso9adc6d42014-11-14 15:37:48 +010089.. _layout_config:
90
Clark Boylan9b670902012-09-28 13:47:56 -070091**layout_config**
James E. Blair4076e2b2014-01-28 12:42:20 -080092 Path to layout config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070093 ``layout_config=/etc/zuul/layout.yaml``
94
95**log_config**
James E. Blaira4430132014-02-17 08:32:07 -080096 Path to log config file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -070097 ``log_config=/etc/zuul/logging.yaml``
98
99**pidfile**
James E. Blaira4430132014-02-17 08:32:07 -0800100 Path to PID lock file. Used by zuul-server only.
Clark Boylan9b670902012-09-28 13:47:56 -0700101 ``pidfile=/var/run/zuul/zuul.pid``
102
103**state_dir**
James E. Blair4076e2b2014-01-28 12:42:20 -0800104 Path to directory that Zuul should save state to. Used by all Zuul
105 commands.
Clark Boylan9b670902012-09-28 13:47:56 -0700106 ``state_dir=/var/lib/zuul``
107
James E. Blair4076e2b2014-01-28 12:42:20 -0800108**report_times**
109 Boolean value (``true`` or ``false``) that determines if Zuul should
110 include elapsed times for each job in the textual report. Used by
111 zuul-server only.
112 ``report_times=true``
113
114**status_url**
115 URL that will be posted in Zuul comments made to Gerrit changes when
116 starting jobs for a change. Used by zuul-server only.
117 ``status_url=https://zuul.example.com/status``
118
Clark Boylane0b4bdb2014-06-03 17:01:25 -0700119**status_expiry**
120 Zuul will cache the status.json file for this many seconds. This is an
121 optional value and ``1`` is used by default.
122 ``status_expiry=1``
123
James E. Blair4076e2b2014-01-28 12:42:20 -0800124**url_pattern**
125 If you are storing build logs external to the system that originally
126 ran jobs and wish to link to those logs when Zuul makes comments on
127 Gerrit changes for completed jobs this setting configures what the
128 URLs for those links should be. Used by zuul-server only.
129 ``http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}``
130
131**job_name_in_report**
132 Boolean value (``true`` or ``false``) that indicates whether the
133 job name should be included in the report (normally only the URL
134 is included). Defaults to ``false``. Used by zuul-server only.
135 ``job_name_in_report=true``
136
137merger
138""""""
139
Clark Boylan9b670902012-09-28 13:47:56 -0700140**git_dir**
141 Directory that Zuul should clone local git repositories to.
142 ``git_dir=/var/lib/zuul/git``
143
Paul Belangerb67aba12013-05-13 19:22:14 -0400144**git_user_email**
145 Optional: Value to pass to `git config user.email`.
146 ``git_user_email=zuul@example.com``
147
148**git_user_name**
149 Optional: Value to pass to `git config user.name`.
150 ``git_user_name=zuul``
151
Arx Cruzb1b010d2013-10-28 19:49:59 -0200152**zuul_url**
James E. Blair4076e2b2014-01-28 12:42:20 -0800153 URL of this merger's git repos, accessible to test workers. Usually
154 "http://zuul.example.com/p" or "http://zuul-merger01.example.com/p"
155 depending on whether the merger is co-located with the Zuul server.
Arx Cruzb1b010d2013-10-28 19:49:59 -0200156
James E. Blaira4430132014-02-17 08:32:07 -0800157**log_config**
158 Path to log config file for the merger process.
159 ``log_config=/etc/zuul/logging.yaml``
160
161**pidfile**
162 Path to PID lock file for the merger process.
163 ``pidfile=/var/run/zuul-merger/merger.pid``
164
Joshua Hesketh5fea8672013-08-19 17:32:01 +1000165smtp
166""""
167
168**server**
169 SMTP server hostname or address to use.
170 ``server=localhost``
171
Akihiro Motokic7d28a72014-03-22 09:21:38 +0900172**port**
173 Optional: SMTP server port.
174 ``port=25``
175
Joshua Hesketh5fea8672013-08-19 17:32:01 +1000176**default_from**
177 Who the email should appear to be sent from when emailing the report.
178 This can be overridden by individual pipelines.
179 ``default_from=zuul@example.com``
180
181**default_to**
182 Who the report should be emailed to by default.
183 This can be overridden by individual pipelines.
184 ``default_to=you@example.com``
185
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100186.. _swift:
187
188swift
189"""""
190
191To send (optional) swift upload instructions this section must be
Antoine Musso62fa2d42014-06-04 22:55:23 +0200192present. Multiple destinations can be defined in the :ref:`jobs` section
193of the layout.
194
195If you are sending the temp-url-key or fetching the x-storage-url, you
196will need the python-swiftclient module installed.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100197
Joshua Heskethc4967502014-05-15 06:39:14 -0700198**X-Account-Meta-Temp-Url-Key** (optional)
199 This is the key used to sign the HMAC message. If you do not set a
200 key Zuul will generate one automatically.
201
202**Send-Temp-Url-Key** (optional)
203 Zuul can send the X-Account-Meta-Temp-Url-Key to swift for you if
204 you have set up the appropriate credentials in ``authurl`` below.
205 This isn't necessary if you know and have set your
206 X-Account-Meta-Temp-Url-Key.
Antoine Musso62fa2d42014-06-04 22:55:23 +0200207 If set, Zuul requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700208 ``default: true``
209
210**X-Storage-Url** (optional)
211 The storage URL is the destination to upload files into. If you do
212 not set this the ``authurl`` credentials are used to fetch the url
Antoine Musso62fa2d42014-06-04 22:55:23 +0200213 from swift and Zuul will requires the python-swiftclient module.
Joshua Heskethc4967502014-05-15 06:39:14 -0700214
215**authurl** (optional)
216 The (keystone) Auth URL for swift.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100217 ``For example, https://identity.api.rackspacecloud.com/v2.0/``
Joshua Heskethc4967502014-05-15 06:39:14 -0700218 This is required if you have Send-Temp-Url-Key set to ``True`` or
219 if you have not supplied the X-Storage-Url.
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100220
221Any of the `swiftclient connection parameters`_ can also be defined
222here by the same name. Including the os_options by their key name (
223``for example tenant_id``)
224
225.. _swiftclient connection parameters: http://docs.openstack.org/developer/python-swiftclient/swiftclient.html#module-swiftclient.client
226
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100227**region_name** (optional)
228 The region name holding the swift container
229 ``For example, SYD``
230
231Each destination defined by the :ref:`jobs` will have the following
232default values that it may overwrite.
233
234**default_container** (optional)
235 Container name to place the log into
236 ``For example, logs``
237
238**default_expiry** (optional)
239 How long the signed destination should be available for
240 ``default: 7200 (2hrs)``
241
242**default_max_file_size** (optional)
243 The maximum size of an individual file
244 ``default: 104857600 (100MB)``
245
246**default_max_file_count** (optional)
247 The maximum number of separate files to allow
248 ``default: 10``
249
250**default_logserver_prefix**
251 Provide a URL to the CDN or logserver app so that a worker knows
252 what URL to return. The worker should return the logserver_prefix
253 url and the object path.
254 ``For example: http://logs.example.org/server.app?obj=``
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
James E. Blaire5a847f2012-07-10 15:29:14 -0700264.. _includes:
265
266Includes
267""""""""
268
269Custom functions to be used in Zuul's configuration may be provided
270using the ``includes`` directive. It accepts a list of files to
271include, and currently supports one type of inclusion, a python file::
272
273 includes:
274 - python-file: local_functions.py
275
276**python-file**
Antoine Musso9adc6d42014-11-14 15:37:48 +0100277 The path to a python file (either an absolute path or relative to the
278 directory name of :ref:`layout_config <layout_config>`). The
279 file will be loaded and objects that it defines will be placed in a
280 special environment which can be referenced in the Zuul configuration.
281 Currently only the parameter-function attribute of a Job uses this
282 feature.
James E. Blaire5a847f2012-07-10 15:29:14 -0700283
Clark Boylan00635dc2012-09-19 14:03:08 -0700284Pipelines
285"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700286
Clark Boylan00635dc2012-09-19 14:03:08 -0700287Zuul can have any number of independent pipelines. Whenever a matching
288Gerrit event is found for a pipeline, that event is added to the
289pipeline, and the jobs specified for that pipeline are run. When all
290jobs specified for the pipeline that were triggered by an event are
291completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700292
Clark Boylan00635dc2012-09-19 14:03:08 -0700293There are no pre-defined pipelines in Zuul, rather you can define
294whatever pipelines you need in the layout file. This is a very flexible
295system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700296
Clark Boylan00635dc2012-09-19 14:03:08 -0700297Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700298explanation of each of the parameters::
299
300 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700301 manager: IndependentPipelineManager
James E. Blairc0dedf82014-08-06 09:37:52 -0700302 source: gerrit
James E. Blaircdd00072012-06-08 19:17:28 -0700303 trigger:
James E. Blair6c358e72013-07-29 17:06:47 -0700304 gerrit:
305 - event: patchset-created
James E. Blaircdd00072012-06-08 19:17:28 -0700306 success:
307 verified: 1
308 failure:
309 verified: -1
310
311**name**
312 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700313 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700314
James E. Blair8dbd56a2012-12-22 10:55:10 -0800315**description**
316 This is an optional field that may be used to provide a textual
317 description of the pipeline.
318
James E. Blairc0dedf82014-08-06 09:37:52 -0700319**source**
320 A required field that specifies a trigger that provides access to
321 the change objects that this pipeline operates on. Currently only
322 the value ``gerrit`` is supported.
323
James E. Blair56370192013-01-14 15:47:28 -0800324**success-message**
325 An optional field that supplies the introductory text in message
326 reported back to Gerrit when all the voting builds are successful.
327 Defaults to "Build successful."
328
329**failure-message**
330 An optional field that supplies the introductory text in message
331 reported back to Gerrit when at least one voting build fails.
332 Defaults to "Build failed."
333
Joshua Heskethb7179772014-01-30 23:30:46 +1100334**merge-failure-message**
335 An optional field that supplies the introductory text in message
336 reported back to Gerrit when a change fails to merge with the
337 current state of the repository.
338 Defaults to "Merge failed."
339
Joshua Hesketh3979e3e2014-03-04 11:21:10 +1100340**footer-message**
341 An optional field to supply additional information after test results.
342 Useful for adding information about the CI system such as debugging
343 and contact details.
344
James E. Blaircdd00072012-06-08 19:17:28 -0700345**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700346 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700347
Clark Boylan00635dc2012-09-19 14:03:08 -0700348 *IndependentPipelineManager*
349 Every event in this pipeline should be treated as independent of
350 other events in the pipeline. This is appropriate when the order of
351 events in the pipeline doesn't matter because the results of the
352 actions this pipeline performs can not affect other events in the
353 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700354 you may want to run tests on that change to provide early feedback
355 to reviewers. At the end of the tests, the change is not going to
356 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700357 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700358
Clark Boylan00635dc2012-09-19 14:03:08 -0700359 Another type of pipeline that is independent is a post-merge
360 pipeline. In that case, the changes have already merged, so the
361 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700362
Clark Boylan00635dc2012-09-19 14:03:08 -0700363 *DependentPipelineManager*
364 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700365 that every change is tested exactly as it is going to be merged
366 into the repository. An ideal gating system would test one change
367 at a time, applied to the tip of the repository, and only if that
368 change passed tests would it be merged. Then the next change in
369 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700370 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700371 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700372 their entry into the pipeline. It begins testing all changes in
373 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700374 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700375 merged in parallel. If a change near the front of the pipeline
376 fails its tests, each change behind it ignores whatever tests have
377 been completed and are tested again without the change in front.
378 This way gate tests may run in parallel but still be tested
379 correctly, exactly as they will appear in the repository when
380 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700381
Clark Boylan00635dc2012-09-19 14:03:08 -0700382 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700383 it analyzes the jobs that are triggered by different projects, and
384 if those projects have jobs in common, it treats those projects as
385 related, and they share a single virtual queue of changes. Thus,
386 if there is a job that performs integration testing on two
387 projects, those two projects will automatically share a virtual
388 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700389 will be part of a separate virtual change queue, and changes to
390 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700391
392 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700393 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700394
395**trigger**
James E. Blairc494d542014-08-06 09:23:52 -0700396 At least one trigger source must be supplied for each pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700397 Triggers are not exclusive -- matching events may be placed in
James E. Blair6c358e72013-07-29 17:06:47 -0700398 multiple pipelines, and they will behave independently in each of
399 the pipelines they match. You may select from the following:
James E. Blaircdd00072012-06-08 19:17:28 -0700400
James E. Blair6c358e72013-07-29 17:06:47 -0700401 **gerrit**
402 This describes what Gerrit events should be placed in the
403 pipeline. Multiple gerrit triggers may be listed. Further
404 parameters describe the kind of events that match:
James E. Blaircdd00072012-06-08 19:17:28 -0700405
James E. Blair6c358e72013-07-29 17:06:47 -0700406 *event*
407 The event name from gerrit. Examples: ``patchset-created``,
408 ``comment-added``, ``ref-updated``. This field is treated as a
409 regular expression.
James E. Blaircdd00072012-06-08 19:17:28 -0700410
James E. Blair6c358e72013-07-29 17:06:47 -0700411 *branch*
412 The branch associated with the event. Example: ``master``. This
413 field is treated as a regular expression, and multiple branches may
414 be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700415
James E. Blair6c358e72013-07-29 17:06:47 -0700416 *ref*
417 On ref-updated events, the branch parameter is not used, instead the
418 ref is provided. Currently Gerrit has the somewhat idiosyncratic
419 behavior of specifying bare refs for branch names (e.g., ``master``),
420 but full ref names for other kinds of refs (e.g., ``refs/tags/foo``).
421 Zuul matches what you put here exactly against what Gerrit
422 provides. This field is treated as a regular expression, and
423 multiple refs may be listed.
James E. Blaircdd00072012-06-08 19:17:28 -0700424
James E. Blair6c358e72013-07-29 17:06:47 -0700425 *approval*
426 This is only used for ``comment-added`` events. It only matches if
427 the event has a matching approval associated with it. Example:
428 ``code-review: 2`` matches a ``+2`` vote on the code review category.
429 Multiple approvals may be listed.
Antoine Mussob4e809e2012-12-06 16:58:06 +0100430
James E. Blair1fbfceb2014-06-23 14:42:53 -0700431 *email*
James E. Blair6c358e72013-07-29 17:06:47 -0700432 This is used for any event. It takes a regex applied on the performer
Michael Prokop526926a2013-10-24 16:16:57 +0200433 email, i.e. Gerrit account email address. If you want to specify
James E. Blair6c358e72013-07-29 17:06:47 -0700434 several email filters, you must use a YAML list. Make sure to use non
435 greedy matchers and to escapes dots!
James E. Blair1fbfceb2014-06-23 14:42:53 -0700436 Example: ``email: ^.*?@example\.org$``.
James E. Blair6c358e72013-07-29 17:06:47 -0700437
James E. Blair1fbfceb2014-06-23 14:42:53 -0700438 *email_filter* (deprecated)
439 A deprecated alternate spelling of *email*. Only one of *email* or
440 *email_filter* should be used.
441
442 *username*
Joshua Heskethb8a817e2013-12-27 11:21:38 +1100443 This is used for any event. It takes a regex applied on the performer
444 username, i.e. Gerrit account name. If you want to specify several
445 username filters, you must use a YAML list. Make sure to use non greedy
446 matchers and to escapes dots!
James E. Blair1fbfceb2014-06-23 14:42:53 -0700447 Example: ``username: ^jenkins$``.
Joshua Heskethb8a817e2013-12-27 11:21:38 +1100448
James E. Blair1fbfceb2014-06-23 14:42:53 -0700449 *username_filter* (deprecated)
450 A deprecated alternate spelling of *username*. Only one of *username* or
451 *username_filter* should be used.
452
453 *comment*
James E. Blair6c358e72013-07-29 17:06:47 -0700454 This is only used for ``comment-added`` events. It accepts a list of
455 regexes that are searched for in the comment string. If any of these
456 regexes matches a portion of the comment string the trigger is
James E. Blair1fbfceb2014-06-23 14:42:53 -0700457 matched. ``comment: retrigger`` will match when comments
James E. Blair6c358e72013-07-29 17:06:47 -0700458 containing 'retrigger' somewhere in the comment text are added to a
459 change.
Clark Boylanb9bcb402012-06-29 17:44:05 -0700460
James E. Blair1fbfceb2014-06-23 14:42:53 -0700461 *comment_filter* (deprecated)
462 A deprecated alternate spelling of *comment*. Only one of *comment* or
463 *comment_filter* should be used.
464
James E. Blair9c17dbf2014-06-23 14:21:58 -0700465 *require-approval*
James E. Blairc053d022014-01-22 14:57:33 -0800466 This may be used for any event. It requires that a certain kind
467 of approval be present for the current patchset of the change (the
James E. Blair11041d22014-05-02 14:49:53 -0700468 approval could be added by the event in question). It follows the
Antoine Musso27ab0d52014-10-22 14:20:17 +0200469 same syntax as the :ref:`"approval" pipeline requirement below
470 <pipeline-require-approval>`.
James E. Blairc053d022014-01-22 14:57:33 -0800471
James E. Blair63bb0ef2013-07-29 17:14:51 -0700472 **timer**
473 This trigger will run based on a cron-style time specification.
474 It will enqueue an event into its pipeline for every project
475 defined in the configuration. Any job associated with the
476 pipeline will run in response to that event.
477
478 *time*
479 The time specification in cron syntax. Only the 5 part syntax is
480 supported, not the symbolic names. Example: ``0 0 * * *`` runs
481 at midnight.
482
James E. Blairc494d542014-08-06 09:23:52 -0700483 **zuul**
484 This trigger supplies events generated internally by Zuul.
485 Multiple events may be listed.
486
487 *event*
488 The event name. Currently supported:
489
490 *project-change-merged* when Zuul merges a change to a project,
491 it generates this event for every open change in the project.
492
493 *parent-change-enqueued* when Zuul enqueues a change into any
494 pipeline, it generates this event for every child of that
495 change.
496
497 *pipeline*
498 Only available for ``parent-change-enqueued`` events. This is the
499 name of the pipeline in which the parent change was enqueued.
500
501 *require-approval*
502 This may be used for any event. It requires that a certain kind
503 of approval be present for the current patchset of the change (the
504 approval could be added by the event in question). It follows the
Antoine Musso27ab0d52014-10-22 14:20:17 +0200505 same syntax as the :ref:`"approval" pipeline requirement below
506 <pipeline-require-approval>`.
James E. Blairc494d542014-08-06 09:23:52 -0700507
508
James E. Blair11041d22014-05-02 14:49:53 -0700509**require**
510 If this section is present, it established pre-requisites for any
511 kind of item entering the Pipeline. Regardless of how the item is
512 to be enqueued (via any trigger or automatic dependency resolution),
513 the conditions specified here must be met or the item will not be
514 enqueued.
515
Antoine Musso27ab0d52014-10-22 14:20:17 +0200516.. _pipeline-require-approval:
517
James E. Blair11041d22014-05-02 14:49:53 -0700518 **approval**
519 This requires that a certain kind of approval be present for the
520 current patchset of the change (the approval could be added by the
521 event in question). It takes several sub-parameters, all of which
522 are optional and are combined together so that there must be an
523 approval matching all specified requirements.
524
525 *username*
526 If present, an approval from this username is required.
527
James E. Blair1fbfceb2014-06-23 14:42:53 -0700528 *email*
James E. Blair11041d22014-05-02 14:49:53 -0700529 If present, an approval with this email address is required. It
530 is treated as a regular expression as above.
531
James E. Blair1fbfceb2014-06-23 14:42:53 -0700532 *email-filter* (deprecated)
533 A deprecated alternate spelling of *email*. Only one of *email* or
534 *email_filter* should be used.
535
James E. Blair11041d22014-05-02 14:49:53 -0700536 *older-than*
537 If present, the approval must be older than this amount of time
538 to match. Provide a time interval as a number with a suffix of
539 "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
540 (seconds). Example ``48h`` or ``2d``.
541
542 *newer-than*
543 If present, the approval must be newer than this amount of time
544 to match. Same format as "older-than".
545
546 Any other field is interpreted as a review category and value
547 pair. For example ``verified: 1`` would require that the approval
James E. Blair9c17dbf2014-06-23 14:21:58 -0700548 be for a +1 vote in the "Verified" column. The value may either
549 be a single value or a list: ``verified: [1, 2]`` would match
550 either a +1 or +2 vote.
James E. Blair11041d22014-05-02 14:49:53 -0700551
552 **open**
553 A boolean value (``true`` or ``false``) that indicates whether the change
554 must be open or closed in order to be enqueued.
555
Clark Boylana9702ad2014-05-08 17:17:24 -0700556 **current-patchset**
557 A boolean value (``true`` or ``false``) that indicates whether the change
558 must be the current patchset in order to be enqueued.
559
James E. Blair11041d22014-05-02 14:49:53 -0700560 **status**
561 A string value that corresponds with the status of the change
562 reported by the trigger. For example, when using the Gerrit
563 trigger, status values such as ``NEW`` or ``MERGED`` may be useful.
James E. Blair63bb0ef2013-07-29 17:14:51 -0700564
James E. Blair2fa50962013-01-30 21:50:41 -0800565**dequeue-on-new-patchset**
566 Normally, if a new patchset is uploaded to a change that is in a
567 pipeline, the existing entry in the pipeline will be removed (with
568 jobs canceled and any dependent changes that can no longer merge as
569 well. To suppress this behavior (and allow jobs to continue
570 running), set this to ``false``. Default: ``true``.
571
James E. Blaircdd00072012-06-08 19:17:28 -0700572**success**
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000573 Describes where Zuul should report to if all the jobs complete
574 successfully.
James E. Blaircdd00072012-06-08 19:17:28 -0700575 This section is optional; if it is omitted, Zuul will run jobs and
576 do nothing on success; it will not even report a message to Gerrit.
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000577 If the section is present, the listed reporter plugins will be
578 asked to report on the jobs.
579 Each reporter's value dictionary is handled by the reporter. See
580 reporters for more details.
James E. Blaircdd00072012-06-08 19:17:28 -0700581
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400582**failure**
James E. Blaircdd00072012-06-08 19:17:28 -0700583 Uses the same syntax as **success**, but describes what Zuul should
584 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700585
Joshua Heskethb7179772014-01-30 23:30:46 +1100586**merge-failure**
587 Uses the same syntax as **success**, but describes what Zuul should
588 do if it is unable to merge in the patchset. If no merge-failure
589 reporters are listed then the ``failure`` reporters will be used to
590 notify of unsuccessful merges.
591
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400592**start**
James E. Blairdc253862012-06-13 17:12:42 -0700593 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700594 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700595 for example, to reset the value of the Verified review category.
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400596
James E. Blair64ed6f22013-07-10 14:07:23 -0700597**precedence**
598 Indicates how the build scheduler should prioritize jobs for
599 different pipelines. Each pipeline may have one precedence, jobs
600 for pipelines with a higher precedence will be run before ones with
601 lower. The value should be one of ``high``, ``normal``, or ``low``.
602 Default: ``normal``.
603
Clark Boylanc2d19e42014-01-23 14:08:58 -0800604**window**
605 DependentPipelineManagers only. Zuul can rate limit
606 DependentPipelineManagers in a manner similar to TCP flow control.
607 Jobs are only started for changes in the queue if they sit in the
608 actionable window for the pipeline. The initial length of this window
609 is configurable with this value. The value given should be a positive
610 integer value. A value of ``0`` disables rate limiting on the
611 DependentPipelineManager.
612 Default: ``20``.
613
614**window-floor**
615 DependentPipelineManagers only. This is the minimum value for the
616 window described above. Should be a positive non zero integer value.
617 Default: ``3``.
618
619**window-increase-type**
620 DependentPipelineManagers only. This value describes how the window
621 should grow when changes are successfully merged by zuul. A value of
622 ``linear`` indicates that ``window-increase-factor`` should be added
623 to the previous window value. A value of ``exponential`` indicates
624 that ``window-increase-factor`` should be multiplied against the
625 previous window value and the result will become the window size.
626 Default: ``linear``.
627
628**window-increase-factor**
629 DependentPipelineManagers only. The value to be added or mulitplied
630 against the previous window value to determine the new window after
631 successful change merges.
632 Default: ``1``.
633
634**window-decrease-type**
635 DependentPipelineManagers only. This value describes how the window
636 should shrink when changes are not able to be merged by Zuul. A value
637 of ``linear`` indicates that ``window-decrease-factor`` should be
638 subtracted from the previous window value. A value of ``exponential``
639 indicates that ``window-decrease-factor`` should be divided against
640 the previous window value and the result will become the window size.
641 Default: ``exponential``.
642
643**window-decrease-factor**
644 DependentPipelineManagers only. The value to be subtracted or divided
645 against the previous window value to determine the new window after
646 unsuccessful change merges.
647 Default: ``2``.
648
Clark Boylan00635dc2012-09-19 14:03:08 -0700649Some example pipeline configurations are included in the sample layout
650file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700651
652 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700653 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700654 trigger:
655 - event: patchset-created
656 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000657 gerrit:
658 verified: 1
James E. Blaircdd00072012-06-08 19:17:28 -0700659 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000660 gerrit:
661 verified: -1
James E. Blaircdd00072012-06-08 19:17:28 -0700662
663This will trigger jobs each time a new patchset (or change) is
664uploaded to Gerrit, and report +/-1 values to Gerrit in the
665``verified`` review category. ::
666
667 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700668 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700669 trigger:
670 - event: comment-added
671 approval:
672 - approved: 1
673 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000674 gerrit:
675 verified: 2
676 submit: true
James E. Blaircdd00072012-06-08 19:17:28 -0700677 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000678 gerrit:
679 verified: -2
James E. Blaircdd00072012-06-08 19:17:28 -0700680
681This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
682``approved`` review category in Gerrit (a non-standard category).
683Changes will be tested in such a way as to guarantee that they will be
684merged exactly as tested, though that will happen in parallel by
685creating a virtual queue of dependent changes and performing
686speculative execution of jobs. ::
687
688 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700689 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700690 trigger:
691 - event: ref-updated
692 ref: ^(?!refs/).*$
693
694This will trigger jobs whenever a change is merged to a named branch
695(e.g., ``master``). No output will be reported to Gerrit. This is
696useful for side effects such as creating per-commit tarballs. ::
697
698 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700699 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700700 trigger:
701 - event: patchset-created
702
703This also triggers jobs when changes are uploaded to Gerrit, but no
704results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200705development and not yet ready to be presented to developers. ::
706
707 pipelines:
708 - name: post-merge
709 manager: IndependentPipelineManager
710 trigger:
711 - event: change-merged
712 success:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000713 gerrit:
714 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200715 failure:
Joshua Hesketh1879cf72013-08-19 14:13:15 +1000716 gerrit:
717 force-message: True
Antoine Mussoce333842012-10-16 14:42:35 +0200718
719The ``change-merged`` events happen when a change has been merged in the git
720repository. The change is thus closed and Gerrit will not accept modifications
721to the review scoring such as ``code-review`` or ``verified``. By using the
722``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
723``gerrit review`` command, thus making sure the message is actually
724sent back to Gerrit regardless of approval scores.
725That kind of pipeline is nice to run regression or performance tests.
726
727.. note::
728 The ``change-merged`` event does not include the commit sha1 which can be
729 hazardous, it would let you report back to Gerrit though. If you were to
Michael Prokop526926a2013-10-24 16:16:57 +0200730 build a tarball for a specific commit, you should consider instead using
Łukasz Jernaś048acb42014-03-02 18:49:41 +0100731 the ``ref-updated`` event which does include the commit sha1 (but lacks the
Antoine Mussoce333842012-10-16 14:42:35 +0200732 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700733
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100734
735.. _jobs:
736
James E. Blaircdd00072012-06-08 19:17:28 -0700737Jobs
738""""
739
740The jobs section is optional, and can be used to set attributes of
741jobs that are independent of their association with a project. For
742example, if a job should return a customized message on failure, that
743may be specified here. Otherwise, Zuul does not need to be told about
744each job as it builds a list from the project specification.
745
746**name**
747 The name of the job. This field is treated as a regular expression
748 and will be applied to each job that matches.
749
James E. Blairc8a1e052014-02-25 09:29:26 -0800750**queue-name (optional)**
751 Zuul will automatically combine projects that share a job into
752 shared change queues for dependent pipeline managers. In order to
753 report statistics about these queues, it is convenient for them to
754 have names. Zuul can automatically name change queues, however
755 these can grow quite long and are prone to changing as projects in
756 the queue change. If you assign a queue-name to a job, Zuul will
757 use that as the name for the shared change queue that contains that
758 job instead of the automatically generated one. It is an error for
759 a shared change queue to have more than one job with a queue-name if
760 they are not the same.
761
James E. Blaire5a847f2012-07-10 15:29:14 -0700762**failure-message (optional)**
763 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700764
James E. Blaire5a847f2012-07-10 15:29:14 -0700765**success-message (optional)**
766 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700767
James E. Blair6aea36d2012-12-17 13:03:24 -0800768**failure-pattern (optional)**
769 The URL that should be reported to Gerrit if the job fails.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700770 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800771 zuul.conf. May be supplied as a string pattern with substitutions
772 as described in url_pattern in :ref:`zuulconf`.
773
774**success-pattern (optional)**
775 The URL that should be reported to Gerrit if the job succeeds.
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700776 Defaults to the build URL or the url_pattern configured in
James E. Blair6aea36d2012-12-17 13:03:24 -0800777 zuul.conf. May be supplied as a string pattern with substitutions
778 as described in url_pattern in :ref:`zuulconf`.
779
James E. Blair222d4982012-07-16 09:31:19 -0700780**hold-following-changes (optional)**
781 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700782 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700783 succeeds before launching. If this is applied to a very short job
784 that can predict whether longer jobs will fail early, this can be
785 used to reduce the number of jobs that Zuul will launch and
786 ultimately have to cancel. In that case, a small amount of
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400787 parallelization of jobs is traded for more efficient use of testing
James E. Blair222d4982012-07-16 09:31:19 -0700788 resources. On the other hand, to apply this to a long running job
789 would largely defeat the parallelization of dependent change testing
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400790 that is the main feature of Zuul. Default: ``false``.
James E. Blair222d4982012-07-16 09:31:19 -0700791
James E. Blaire5a847f2012-07-10 15:29:14 -0700792**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700793 This job should only be run on matching branches. This field is
794 treated as a regular expression and multiple branches may be
795 listed.
796
James E. Blair70c71582013-03-06 08:50:50 -0800797**files (optional)**
798 This job should only be run if at least one of the files involved in
799 the change (added, deleted, or modified) matches at least one of the
800 file patterns listed here. This field is treated as a regular
801 expression and multiple expressions may be listed.
802
Mathieu Gagnéd6d2a642013-06-11 20:59:58 -0400803**voting (optional)**
804 Boolean value (``true`` or ``false``) that indicates whatever
805 a job is voting or not. Default: ``true``.
806
James E. Blaire5a847f2012-07-10 15:29:14 -0700807**parameter-function (optional)**
808 Specifies a function that should be applied to the parameters before
809 the job is launched. The function should be defined in a python file
810 included with the :ref:`includes` directive. The function
811 should have the following signature:
812
James E. Blaird0470972013-07-29 10:05:43 -0700813 .. function:: parameters(item, job, parameters)
James E. Blaire5a847f2012-07-10 15:29:14 -0700814
815 Manipulate the parameters passed to a job before a build is
816 launched. The ``parameters`` dictionary will already contain the
817 standard Zuul job parameters, and is expected to be modified
818 in-place.
819
James E. Blaird78576a2013-07-09 10:39:17 -0700820 :param item: the current queue item
821 :type item: zuul.model.QueueItem
James E. Blaird0470972013-07-29 10:05:43 -0700822 :param job: the job about to be run
823 :type job: zuul.model.Job
James E. Blaire5a847f2012-07-10 15:29:14 -0700824 :param parameters: parameters to be passed to the job
825 :type parameters: dict
826
James E. Blair1f4c2bb2013-04-26 08:40:46 -0700827 If the parameter **ZUUL_NODE** is set by this function, then it will
828 be used to specify on what node (or class of node) the job should be
829 run.
830
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100831**swift**
832 If :ref:`swift` is configured then each job can define a destination
833 container for the builder to place logs and/or assets into. Multiple
834 containers can be listed for each job by providing a unique ``name``.
835
836 *name*
837 Set an identifying name for the container. This is used in the
838 parameter key sent to the builder. For example if it ``logs`` then
839 one of the parameters sent will be ``SWIFT_logs_CONTAINER``
840 (case-sensitive).
841
842 Each of the defaults defined in :ref:`swift` can be overwritten as:
843
844 *container* (optional)
845 Container name to place the log into
846 ``For example, logs``
847
848 *expiry* (optional)
849 How long the signed destination should be available for
850
James E. Blaird6500232014-06-23 15:05:48 -0700851 *max-file-size** (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100852 The maximum size of an individual file
853
James E. Blaird6500232014-06-23 15:05:48 -0700854 *max_file_size** (optional, deprecated)
855 A deprecated alternate spelling of *max-file-size*.
856
857 *max-file-count* (optional)
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100858 The maximum number of separate files to allow
859
James E. Blaird6500232014-06-23 15:05:48 -0700860 *max_file_count* (optional, deprecated)
861 A deprecated alternate spelling of *max-file-count*.
862
863 *logserver-prefix*
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100864 Provide a URL to the CDN or logserver app so that a worker knows
865 what URL to return.
866 ``For example: http://logs.example.org/server.app?obj=``
James E. Blaird6500232014-06-23 15:05:48 -0700867 The worker should return the logserver-prefix url and the object
Joshua Hesketh36c3fa52014-01-22 11:40:52 +1100868 path as the URL in the results data packet.
869
James E. Blaird6500232014-06-23 15:05:48 -0700870 *logserver_prefix* (deprecated)
871 A deprecated alternate spelling of *logserver-prefix*.
872
James E. Blaircdd00072012-06-08 19:17:28 -0700873Here is an example of setting the failure message for jobs that check
874whether a change merges cleanly::
875
876 - name: ^.*-merge$
877 failure-message: This change was unable to be automatically merged
878 with the current state of the repository. Please rebase your
879 change and upload a new patchset.
880
881Projects
882""""""""
883
Clark Boylan00635dc2012-09-19 14:03:08 -0700884The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700885for events associated with each project. It contains a list of
886projects. Here is an example::
887
888 - name: example/project
889 check:
890 - project-merge:
891 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700892 - project-pep8
893 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700894 gate:
895 - project-merge:
896 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700897 - project-pep8
898 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700899 post:
900 - project-publish
901
902**name**
903 The name of the project (as known by Gerrit).
904
James E. Blair19deff22013-08-25 13:17:35 -0700905**merge-mode (optional)**
906 An optional value that indicates what strategy should be used to
907 merge changes to this project. Supported values are:
908
909 ** merge-resolve **
910 Equivalent to 'git merge -s resolve'. This corresponds closely to
911 what Gerrit performs (using JGit) for a project if the "Merge if
912 necessary" merge mode is selected and "Automatically resolve
913 conflicts" is checked. This is the default.
914
915 ** merge **
916 Equivalent to 'git merge'.
917
918 ** cherry-pick **
919 Equivalent to 'git cherry-pick'.
920
Clark Boylan00635dc2012-09-19 14:03:08 -0700921This is followed by a section for each of the pipelines defined above.
922Pipelines may be omitted if no jobs should run for this project in a
923given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700924executed are listed. If a job is entered as a dictionary key, then
925jobs contained within that key are only executed if the key job
926succeeds. In the above example, project-unittest, project-pep8, and
927project-pyflakes are only executed if project-merge succeeds. This
928can help avoid running unnecessary jobs.
929
James E. Blair18c64442014-03-18 10:14:45 -0700930The special job named ``noop`` is internal to Zuul and will always
931return ``SUCCESS`` immediately. This can be useful if you require
932that all changes be processed by a pipeline but a project has no jobs
933that can be run on it.
934
Andreas Jaegerbcfbf932014-09-29 20:21:44 +0200935.. 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 -0700936
Antoine Musso80edd5a2013-02-13 15:37:53 +0100937Project Templates
938"""""""""""""""""
939
Michael Prokop526926a2013-10-24 16:16:57 +0200940Whenever you have lot of similar projects (such as plugins for a project) you
Antoine Musso80edd5a2013-02-13 15:37:53 +0100941will most probably want to use the same pipeline configurations. The
942project templates let you define pipelines and job name templates to trigger.
943One can then just apply the template on its project which make it easier to
Michael Prokop526926a2013-10-24 16:16:57 +0200944update several similar projects. As an example::
Antoine Musso80edd5a2013-02-13 15:37:53 +0100945
946 project-templates:
947 # Name of the template
948 - name: plugin-triggering
949 # Definition of pipelines just like for a `project`
950 check:
951 - '{jobprefix}-merge':
952 - '{jobprefix}-pep8'
953 - '{jobprefix}-pyflakes'
954 gate:
955 - '{jobprefix}-merge':
956 - '{jobprefix}-unittest'
957 - '{jobprefix}-pep8'
958 - '{jobprefix}-pyflakes'
959
960In your projects definition, you will then apply the template using the template
961key::
962
963 projects:
964 - name: plugin/foobar
965 template:
966 - name: plugin-triggering
967 jobprefix: plugin-foobar
968
James E. Blairaea6cf62013-12-16 15:38:12 -0800969You can pass several parameters to a template. A ``parameter`` value
970will be used for expansion of ``{parameter}`` in the template
971strings. The parameter ``name`` will be automatically provided and
972will contain the short name of the project, that is the portion of the
973project name after the last ``/`` character.
James E. Blaircdd00072012-06-08 19:17:28 -0700974
James E. Blair3e98c022013-12-16 15:25:38 -0800975Multiple templates can be combined in a project, and the jobs from all
976of those templates will be added to the project. Individual jobs may
977also be added::
978
979 projects:
980 - name: plugin/foobar
981 template:
982 - name: plugin-triggering
983 jobprefix: plugin-foobar
984 - name: plugin-extras
985 jobprefix: plugin-foobar
986 check:
987 - foobar-extra-special-job
988
Steven Dake21ef9ad2014-08-25 23:08:14 -0700989Individual jobs may optionally be added to pipelines (e.g. check,
990gate, et cetera) for a project, in addtion to those provided by
991templates.
992
James E. Blair3e98c022013-12-16 15:25:38 -0800993The order of the jobs listed in the project (which only affects the
994order of jobs listed on the report) will be the jobs from each
995template in the order listed, followed by any jobs individually listed
996for the project.
997
998Note that if multiple templates are used for a project and one
999template specifies a job that is also specified in another template,
James E. Blair12a92b12014-03-26 11:54:53 -07001000or specified in the project itself, the configuration defined by
1001either the last template or the project itself will take priority.
James E. Blair3e98c022013-12-16 15:25:38 -08001002
James E. Blaircdd00072012-06-08 19:17:28 -07001003logging.conf
1004~~~~~~~~~~~~
1005This file is optional. If provided, it should be a standard
1006:mod:`logging.config` module configuration file. If not present, Zuul will
1007output all log messages of DEBUG level or higher to the console.
1008
1009Starting Zuul
1010-------------
1011
1012To start Zuul, run **zuul-server**::
1013
Antoine Mussob3aa8282013-04-19 15:16:59 +02001014 usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]
James E. Blaircdd00072012-06-08 19:17:28 -07001015
1016 Project gating system.
1017
1018 optional arguments:
1019 -h, --help show this help message and exit
1020 -c CONFIG specify the config file
Antoine Mussob3aa8282013-04-19 15:16:59 +02001021 -l LAYOUT specify the layout file
James E. Blaircdd00072012-06-08 19:17:28 -07001022 -d do not run as a daemon
Antoine Mussob3aa8282013-04-19 15:16:59 +02001023 -t validate layout file syntax
1024 --version show zuul version
James E. Blaircdd00072012-06-08 19:17:28 -07001025
1026You may want to use the ``-d`` argument while you are initially setting
1027up Zuul so you can detect any configuration errors quickly. Under
1028normal operation, omit ``-d`` and let Zuul run as a daemon.
1029
1030If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
1031stop executing new jobs, wait until all executing jobs are finished,
1032reload its configuration, and resume. Any values in any of the
1033configuration files may be changed, except the location of Zuul's PID
1034file (a change to that will be ignored until Zuul is restarted).
Clark Boylanf231fa22013-02-08 12:28:53 -08001035
1036If you send a SIGUSR1 to the zuul-server process, Zuul will stop
1037executing new jobs, wait until all executing jobs are finished,
1038then exit. While waiting to exit Zuul will queue Gerrit events and
1039save these events prior to exiting. When Zuul starts again it will
1040read these saved events and act on them.
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001041
Michael Prokop526926a2013-10-24 16:16:57 +02001042If you need to abort Zuul and intend to manually requeue changes for
Jeremy Stanley93e05f42013-03-08 17:29:17 +00001043jobs which were running in its pipelines, prior to terminating you can
1044use the zuul-changes.py tool script to simplify the process. For
1045example, this would give you a list of Gerrit commands to reverify or
1046recheck changes for the gate and check pipelines respectively::
1047
1048 ./tools/zuul-changes.py --review-host=review.openstack.org \
1049 http://zuul.openstack.org/ gate 'reverify no bug'
1050 ./tools/zuul-changes.py --review-host=review.openstack.org \
1051 http://zuul.openstack.org/ check 'recheck no bug'
Clark Boylanfba9b242013-08-20 10:11:17 -07001052
1053If you send a SIGUSR2 to the zuul-server process, Zuul will dump a stack
1054trace for each running thread into its debug log. This is useful for
1055tracking down deadlock or otherwise slow threads.
Antoine Mussod0f06262014-06-04 09:54:24 +02001056
1057When `yappi <https://code.google.com/p/yappi/>`_ (Yet Another Python
1058Profiler) is available, additional functions' and threads' stats are
1059emitted as well. The first SIGUSR2 will enable yappi, on the second
1060SIGUSR2 it dumps the information collected, resets all yappi state and
1061stops profiling. This is to minimize the impact of yappi on a running
1062system.