blob: 0c4d076a7601e17547d90a43ab36739c4d47455d [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**
12 Credentials for Gerrit and Jenkins, locations of the other config files
13**layout.yaml**
Clark Boylan00635dc2012-09-19 14:03:08 -070014 Project and pipeline configuration -- what Zuul does
James E. Blaircdd00072012-06-08 19:17:28 -070015**logging.conf**
16 Python logging config
17
18Examples of each of the three files can be found in the etc/ directory
19of the source distribution.
20
James E. Blair6aea36d2012-12-17 13:03:24 -080021.. _zuulconf:
22
James E. Blaircdd00072012-06-08 19:17:28 -070023zuul.conf
24~~~~~~~~~
25
26Zuul will look for ``/etc/zuul/zuul.conf`` or ``~/zuul.conf`` to
27bootstrap its configuration. Alternately, you may specify ``-c
28/path/to/zuul.conf`` on the command line.
29
30Gerrit and Jenkins credentials are each described in a section of
31zuul.conf. The location of the other two configuration files (as well
32as the location of the PID file when running Zuul as a server) are
33specified in a third section.
34
Clark Boylan9b670902012-09-28 13:47:56 -070035The three sections of this config and their options are documented below.
36You can also find an example zuul.conf file in the git
37`repository
38<https://github.com/openstack-ci/zuul/blob/master/etc/zuul.conf-sample>`_
39
40jenkins
41"""""""
42
43**server**
44 URL for the root of the Jenkins HTTP server.
45 ``server=https://jenkins.example.com``
46
47**user**
48 User to authenticate against Jenkins with.
49 ``user=jenkins``
50
51**apikey**
52 Jenkins API Key credentials for the above user.
53 ``apikey=1234567890abcdef1234567890abcdef``
54
55gerrit
56""""""
57
58**server**
59 FQDN of Gerrit server.
60 ``server=review.example.com``
61
Antoine Musso27475012012-11-26 09:53:01 +010062**baseurl**
63 Optional: path to Gerrit web interface. Defaults to ``https://<value
64 of server>/``. ``baseurl=https://review.example.com/review_site/``
65
Clark Boylan9b670902012-09-28 13:47:56 -070066**user**
67 User name to use when logging into above server via ssh.
68 ``user=jenkins``
69
70**sshkey**
71 Path to SSH key to use when logging into above server.
72 ``sshkey=/home/jenkins/.ssh/id_rsa``
73
74zuul
75""""
76
77**layout_config**
78 Path to layout config file.
79 ``layout_config=/etc/zuul/layout.yaml``
80
81**log_config**
82 Path to log config file.
83 ``log_config=/etc/zuul/logging.yaml``
84
85**pidfile**
86 Path to PID lock file.
87 ``pidfile=/var/run/zuul/zuul.pid``
88
89**state_dir**
90 Path to directory that Zuul should save state to.
91 ``state_dir=/var/lib/zuul``
92
93**git_dir**
94 Directory that Zuul should clone local git repositories to.
95 ``git_dir=/var/lib/zuul/git``
96
97**push_change_refs**
98 Boolean value (``true`` or ``false``) that determines if Zuul should
99 push change refs to the git origin server for the git repositories in
100 git_dir.
101 ``push_change_refs=true``
102
103**status_url**
104 URL that will be posted in Zuul comments made to Gerrit changes when
105 beginning Jenkins jobs for a change.
106 ``status_url=https://jenkins.example.com/zuul/status``
107
108**url_pattern**
109 If you are storing build logs external to Jenkins and wish to link to
110 those logs when Zuul makes comments on Gerrit changes for completed
111 jobs this setting configures what the URLs for those links should be.
112 ``http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}``
113
James E. Blaircdd00072012-06-08 19:17:28 -0700114layout.yaml
115~~~~~~~~~~~
116
Clark Boylan00635dc2012-09-19 14:03:08 -0700117This is the main configuration file for Zuul, where all of the pipelines
James E. Blaircdd00072012-06-08 19:17:28 -0700118and projects are defined, what tests should be run, and what actions
Clark Boylan00635dc2012-09-19 14:03:08 -0700119Zuul should perform. There are three sections: pipelines, jobs, and
James E. Blaircdd00072012-06-08 19:17:28 -0700120projects.
121
James E. Blaire5a847f2012-07-10 15:29:14 -0700122.. _includes:
123
124Includes
125""""""""
126
127Custom functions to be used in Zuul's configuration may be provided
128using the ``includes`` directive. It accepts a list of files to
129include, and currently supports one type of inclusion, a python file::
130
131 includes:
132 - python-file: local_functions.py
133
134**python-file**
135 The path to a python file. The file will be loaded and objects that
136 it defines will be placed in a special environment which can be
137 referenced in the Zuul configuration. Currently only the
138 parameter-function attribute of a Job uses this feature.
139
Clark Boylan00635dc2012-09-19 14:03:08 -0700140Pipelines
141"""""""""
James E. Blaircdd00072012-06-08 19:17:28 -0700142
Clark Boylan00635dc2012-09-19 14:03:08 -0700143Zuul can have any number of independent pipelines. Whenever a matching
144Gerrit event is found for a pipeline, that event is added to the
145pipeline, and the jobs specified for that pipeline are run. When all
146jobs specified for the pipeline that were triggered by an event are
147completed, Zuul reports back to Gerrit the results.
James E. Blaircdd00072012-06-08 19:17:28 -0700148
Clark Boylan00635dc2012-09-19 14:03:08 -0700149There are no pre-defined pipelines in Zuul, rather you can define
150whatever pipelines you need in the layout file. This is a very flexible
151system that can accommodate many kinds of workflows.
James E. Blaircdd00072012-06-08 19:17:28 -0700152
Clark Boylan00635dc2012-09-19 14:03:08 -0700153Here is a quick example of a pipeline definition followed by an
James E. Blaircdd00072012-06-08 19:17:28 -0700154explanation of each of the parameters::
155
156 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700157 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700158 trigger:
159 - event: patchset-created
160 success:
161 verified: 1
162 failure:
163 verified: -1
164
165**name**
166 This is used later in the project definition to indicate what jobs
Clark Boylan00635dc2012-09-19 14:03:08 -0700167 should be run for events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700168
James E. Blair8dbd56a2012-12-22 10:55:10 -0800169**description**
170 This is an optional field that may be used to provide a textual
171 description of the pipeline.
172
James E. Blair56370192013-01-14 15:47:28 -0800173**success-message**
174 An optional field that supplies the introductory text in message
175 reported back to Gerrit when all the voting builds are successful.
176 Defaults to "Build successful."
177
178**failure-message**
179 An optional field that supplies the introductory text in message
180 reported back to Gerrit when at least one voting build fails.
181 Defaults to "Build failed."
182
James E. Blaircdd00072012-06-08 19:17:28 -0700183**manager**
Clark Boylan00635dc2012-09-19 14:03:08 -0700184 There are currently two schemes for managing pipelines:
James E. Blaircdd00072012-06-08 19:17:28 -0700185
Clark Boylan00635dc2012-09-19 14:03:08 -0700186 *IndependentPipelineManager*
187 Every event in this pipeline should be treated as independent of
188 other events in the pipeline. This is appropriate when the order of
189 events in the pipeline doesn't matter because the results of the
190 actions this pipeline performs can not affect other events in the
191 pipeline. For example, when a change is first uploaded for review,
James E. Blaircdd00072012-06-08 19:17:28 -0700192 you may want to run tests on that change to provide early feedback
193 to reviewers. At the end of the tests, the change is not going to
194 be merged, so it is safe to run these tests in parallel without
Clark Boylan00635dc2012-09-19 14:03:08 -0700195 regard to any other changes in the pipeline. They are independent.
James E. Blaircdd00072012-06-08 19:17:28 -0700196
Clark Boylan00635dc2012-09-19 14:03:08 -0700197 Another type of pipeline that is independent is a post-merge
198 pipeline. In that case, the changes have already merged, so the
199 results can not affect any other events in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700200
Clark Boylan00635dc2012-09-19 14:03:08 -0700201 *DependentPipelineManager*
202 The dependent pipeline manager is designed for gating. It ensures
James E. Blaircdd00072012-06-08 19:17:28 -0700203 that every change is tested exactly as it is going to be merged
204 into the repository. An ideal gating system would test one change
205 at a time, applied to the tip of the repository, and only if that
206 change passed tests would it be merged. Then the next change in
207 line would be tested the same way. In order to achieve parallel
Clark Boylan00635dc2012-09-19 14:03:08 -0700208 testing of changes, the dependent pipeline manager performs
James E. Blaircdd00072012-06-08 19:17:28 -0700209 speculative execution on changes. It orders changes based on
Clark Boylan00635dc2012-09-19 14:03:08 -0700210 their entry into the pipeline. It begins testing all changes in
211 parallel, assuming that each change ahead in the pipeline will pass
James E. Blaircdd00072012-06-08 19:17:28 -0700212 its tests. If they all succeed, all the changes can be tested and
Clark Boylan00635dc2012-09-19 14:03:08 -0700213 merged in parallel. If a change near the front of the pipeline
214 fails its tests, each change behind it ignores whatever tests have
215 been completed and are tested again without the change in front.
216 This way gate tests may run in parallel but still be tested
217 correctly, exactly as they will appear in the repository when
218 merged.
James E. Blaircdd00072012-06-08 19:17:28 -0700219
Clark Boylan00635dc2012-09-19 14:03:08 -0700220 One important characteristic of the DependentPipelineManager is that
James E. Blaircdd00072012-06-08 19:17:28 -0700221 it analyzes the jobs that are triggered by different projects, and
222 if those projects have jobs in common, it treats those projects as
223 related, and they share a single virtual queue of changes. Thus,
224 if there is a job that performs integration testing on two
225 projects, those two projects will automatically share a virtual
226 change queue. If a third project does not invoke that job, it
Clark Boylan00635dc2012-09-19 14:03:08 -0700227 will be part of a separate virtual change queue, and changes to
228 it will not depend on changes to the first two jobs.
James E. Blaircdd00072012-06-08 19:17:28 -0700229
230 For more detail on the theory and operation of Zuul's
Clark Boylan00635dc2012-09-19 14:03:08 -0700231 DependentPipelineManager, see: :doc:`gating`.
James E. Blaircdd00072012-06-08 19:17:28 -0700232
233**trigger**
Clark Boylan00635dc2012-09-19 14:03:08 -0700234 This describes what Gerrit events should be placed in the pipeline.
James E. Blaircdd00072012-06-08 19:17:28 -0700235 Triggers are not exclusive -- matching events may be placed in
Clark Boylan00635dc2012-09-19 14:03:08 -0700236 multiple pipelines, and they will behave independently in each of the
237 pipelines they match. Multiple triggers may be listed. Further
James E. Blaircdd00072012-06-08 19:17:28 -0700238 parameters describe the kind of events that match:
239
240 *event*
241 The event name from gerrit. Examples: ``patchset-created``,
242 ``comment-added``, ``ref-updated``. This field is treated as a
243 regular expression.
244
245 *branch*
246 The branch associated with the event. Example: ``master``. This
247 field is treated as a regular expression, and multiple branches may
248 be listed.
249
250 *ref*
251 On ref-updated events, the branch parameter is not used, instead the
252 ref is provided. Currently Gerrit has the somewhat idiosyncratic
253 behavior of specifying bare refs for branch names (e.g., ``master``),
254 but full ref names for other kinds of refs (e.g., ``refs/tags/foo``).
255 Zuul matches what you put here exactly against what Gerrit
256 provides. This field is treated as a regular expression, and
257 multiple refs may be listed.
258
259 *approval*
260 This is only used for ``comment-added`` events. It only matches if
261 the event has a matching approval associated with it. Example:
262 ``code-review: 2`` matches a ``+2`` vote on the code review category.
263 Multiple approvals may be listed.
264
Antoine Mussob4e809e2012-12-06 16:58:06 +0100265 *email_filter*
266 This is used for any event. It takes a regex applied on the performer
Antoine Musso5f110422012-12-18 23:22:13 +0100267 email, i.e Gerrit account email address. If you want to specify
268 several email filters, you must use a YAML list. Make sure to use non
269 greedy matchers and to escapes dots!
270 Example: ``email_filter: ^.*?@example\.org$``.
Antoine Mussob4e809e2012-12-06 16:58:06 +0100271
Clark Boylanb9bcb402012-06-29 17:44:05 -0700272 *comment_filter*
273 This is only used for ``comment-added`` events. It accepts a list of
274 regexes that are searched for in the comment string. If any of these
275 regexes matches a portion of the comment string the trigger is
276 matched. ``comment_filter: retrigger`` will match when comments
277 containing 'retrigger' somewhere in the comment text are added to a
278 change.
279
James E. Blaircdd00072012-06-08 19:17:28 -0700280**success**
281 Describes what Zuul should do if all the jobs complete successfully.
282 This section is optional; if it is omitted, Zuul will run jobs and
283 do nothing on success; it will not even report a message to Gerrit.
284 If the section is present, it will leave a message on the Gerrit
285 review. Each additional argument is assumed to be an argument to
286 ``gerrit review``, with the boolean value of ``true`` simply
287 indicating that the argument should be present without following it
288 with a value. For example, ``verified: 1`` becomes ``gerrit
289 review --verified 1`` and ``submit: true`` becomes ``gerrit review
290 --submit``.
291
292**failure**
293 Uses the same syntax as **success**, but describes what Zuul should
294 do if at least one job fails.
James E. Blairdc253862012-06-13 17:12:42 -0700295
296**start**
297 Uses the same syntax as **success**, but describes what Zuul should
Clark Boylan00635dc2012-09-19 14:03:08 -0700298 do when a change is added to the pipeline manager. This can be used,
James E. Blairdc253862012-06-13 17:12:42 -0700299 for example, to reset the value of the Verified review category.
James E. Blaircdd00072012-06-08 19:17:28 -0700300
Clark Boylan00635dc2012-09-19 14:03:08 -0700301Some example pipeline configurations are included in the sample layout
302file. The first is called a *check* pipeline::
James E. Blaircdd00072012-06-08 19:17:28 -0700303
304 - name: check
Clark Boylan00635dc2012-09-19 14:03:08 -0700305 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700306 trigger:
307 - event: patchset-created
308 success:
309 verified: 1
310 failure:
311 verified: -1
312
313This will trigger jobs each time a new patchset (or change) is
314uploaded to Gerrit, and report +/-1 values to Gerrit in the
315``verified`` review category. ::
316
317 - name: gate
Clark Boylan00635dc2012-09-19 14:03:08 -0700318 manager: DependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700319 trigger:
320 - event: comment-added
321 approval:
322 - approved: 1
323 success:
324 verified: 2
325 submit: true
326 failure:
327 verified: -2
328
329This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
330``approved`` review category in Gerrit (a non-standard category).
331Changes will be tested in such a way as to guarantee that they will be
332merged exactly as tested, though that will happen in parallel by
333creating a virtual queue of dependent changes and performing
334speculative execution of jobs. ::
335
336 - name: post
Clark Boylan00635dc2012-09-19 14:03:08 -0700337 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700338 trigger:
339 - event: ref-updated
340 ref: ^(?!refs/).*$
341
342This will trigger jobs whenever a change is merged to a named branch
343(e.g., ``master``). No output will be reported to Gerrit. This is
344useful for side effects such as creating per-commit tarballs. ::
345
346 - name: silent
Clark Boylan00635dc2012-09-19 14:03:08 -0700347 manager: IndependentPipelineManager
James E. Blaircdd00072012-06-08 19:17:28 -0700348 trigger:
349 - event: patchset-created
350
351This also triggers jobs when changes are uploaded to Gerrit, but no
352results are reported to Gerrit. This is useful for jobs that are in
Antoine Mussoce333842012-10-16 14:42:35 +0200353development and not yet ready to be presented to developers. ::
354
355 pipelines:
356 - name: post-merge
357 manager: IndependentPipelineManager
358 trigger:
359 - event: change-merged
360 success:
361 force-message: True
362 failure:
363 force-message: True
364
365The ``change-merged`` events happen when a change has been merged in the git
366repository. The change is thus closed and Gerrit will not accept modifications
367to the review scoring such as ``code-review`` or ``verified``. By using the
368``force-message: True`` parameter, Zuul will pass ``--force-message`` to the
369``gerrit review`` command, thus making sure the message is actually
370sent back to Gerrit regardless of approval scores.
371That kind of pipeline is nice to run regression or performance tests.
372
373.. note::
374 The ``change-merged`` event does not include the commit sha1 which can be
375 hazardous, it would let you report back to Gerrit though. If you were to
376 build a tarball for a specific commit, you should consider insteading using
377 the ``ref-updated`` event which does include the commit sha1 (but lack the
378 Gerrit change number).
James E. Blaircdd00072012-06-08 19:17:28 -0700379
380Jobs
381""""
382
383The jobs section is optional, and can be used to set attributes of
384jobs that are independent of their association with a project. For
385example, if a job should return a customized message on failure, that
386may be specified here. Otherwise, Zuul does not need to be told about
387each job as it builds a list from the project specification.
388
389**name**
390 The name of the job. This field is treated as a regular expression
391 and will be applied to each job that matches.
392
James E. Blaire5a847f2012-07-10 15:29:14 -0700393**failure-message (optional)**
394 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700395
James E. Blaire5a847f2012-07-10 15:29:14 -0700396**success-message (optional)**
397 The message that should be reported to Gerrit if the job fails.
James E. Blaircdd00072012-06-08 19:17:28 -0700398
James E. Blair6aea36d2012-12-17 13:03:24 -0800399**failure-pattern (optional)**
400 The URL that should be reported to Gerrit if the job fails.
401 Defaults to the Jenkins build URL or the url_pattern configured in
402 zuul.conf. May be supplied as a string pattern with substitutions
403 as described in url_pattern in :ref:`zuulconf`.
404
405**success-pattern (optional)**
406 The URL that should be reported to Gerrit if the job succeeds.
407 Defaults to the Jenkins build URL or the url_pattern configured in
408 zuul.conf. May be supplied as a string pattern with substitutions
409 as described in url_pattern in :ref:`zuulconf`.
410
James E. Blair222d4982012-07-16 09:31:19 -0700411**hold-following-changes (optional)**
412 This is a boolean that indicates that changes that follow this
Clark Boylan00635dc2012-09-19 14:03:08 -0700413 change in a dependent change pipeline should wait until this job
James E. Blair222d4982012-07-16 09:31:19 -0700414 succeeds before launching. If this is applied to a very short job
415 that can predict whether longer jobs will fail early, this can be
416 used to reduce the number of jobs that Zuul will launch and
417 ultimately have to cancel. In that case, a small amount of
418 paralellization of jobs is traded for more efficient use of testing
419 resources. On the other hand, to apply this to a long running job
420 would largely defeat the parallelization of dependent change testing
421 that is the main feature of Zuul. The default is False.
422
James E. Blaire5a847f2012-07-10 15:29:14 -0700423**branch (optional)**
James E. Blaircdd00072012-06-08 19:17:28 -0700424 This job should only be run on matching branches. This field is
425 treated as a regular expression and multiple branches may be
426 listed.
427
James E. Blaire5a847f2012-07-10 15:29:14 -0700428**parameter-function (optional)**
429 Specifies a function that should be applied to the parameters before
430 the job is launched. The function should be defined in a python file
431 included with the :ref:`includes` directive. The function
432 should have the following signature:
433
434 .. function:: parameters(change, parameters)
435
436 Manipulate the parameters passed to a job before a build is
437 launched. The ``parameters`` dictionary will already contain the
438 standard Zuul job parameters, and is expected to be modified
439 in-place.
440
441 :param change: the current change
442 :type change: zuul.model.Change
443 :param parameters: parameters to be passed to the job
444 :type parameters: dict
445
James E. Blaircdd00072012-06-08 19:17:28 -0700446Here is an example of setting the failure message for jobs that check
447whether a change merges cleanly::
448
449 - name: ^.*-merge$
450 failure-message: This change was unable to be automatically merged
451 with the current state of the repository. Please rebase your
452 change and upload a new patchset.
453
454Projects
455""""""""
456
Clark Boylan00635dc2012-09-19 14:03:08 -0700457The projects section indicates what jobs should be run in each pipeline
James E. Blaircdd00072012-06-08 19:17:28 -0700458for events associated with each project. It contains a list of
459projects. Here is an example::
460
461 - name: example/project
462 check:
463 - project-merge:
464 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700465 - project-pep8
466 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700467 gate:
468 - project-merge:
469 - project-unittest
Clark Boylan00635dc2012-09-19 14:03:08 -0700470 - project-pep8
471 - project-pyflakes
James E. Blaircdd00072012-06-08 19:17:28 -0700472 post:
473 - project-publish
474
475**name**
476 The name of the project (as known by Gerrit).
477
Clark Boylan00635dc2012-09-19 14:03:08 -0700478This is followed by a section for each of the pipelines defined above.
479Pipelines may be omitted if no jobs should run for this project in a
480given pipeline. Within the pipeline section, the jobs that should be
James E. Blaircdd00072012-06-08 19:17:28 -0700481executed are listed. If a job is entered as a dictionary key, then
482jobs contained within that key are only executed if the key job
483succeeds. In the above example, project-unittest, project-pep8, and
484project-pyflakes are only executed if project-merge succeeds. This
485can help avoid running unnecessary jobs.
486
Antoine Mussofec5c7a2012-09-22 12:32:37 +0200487.. seealso:: The OpenStack Zuul configuration for a comprehensive example: https://github.com/openstack/openstack-ci-puppet/blob/master/modules/openstack_project/files/zuul/layout.yaml
James E. Blaircdd00072012-06-08 19:17:28 -0700488
489
490logging.conf
491~~~~~~~~~~~~
492This file is optional. If provided, it should be a standard
493:mod:`logging.config` module configuration file. If not present, Zuul will
494output all log messages of DEBUG level or higher to the console.
495
496Starting Zuul
497-------------
498
499To start Zuul, run **zuul-server**::
500
501 usage: zuul-server [-h] [-c CONFIG] [-d]
502
503 Project gating system.
504
505 optional arguments:
506 -h, --help show this help message and exit
507 -c CONFIG specify the config file
508 -d do not run as a daemon
509
510You may want to use the ``-d`` argument while you are initially setting
511up Zuul so you can detect any configuration errors quickly. Under
512normal operation, omit ``-d`` and let Zuul run as a daemon.
513
514If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will
515stop executing new jobs, wait until all executing jobs are finished,
516reload its configuration, and resume. Any values in any of the
517configuration files may be changed, except the location of Zuul's PID
518file (a change to that will be ignored until Zuul is restarted).