1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
|
:title: Gerrit Driver
Gerrit
======
`Gerrit`_ is a code review system. The Gerrit driver supports
sources, triggers, and reporters.
.. _Gerrit: https://www.gerritcodereview.com/
Zuul will need access to a Gerrit user.
Create an SSH keypair for Zuul to use if there isn't one already, and
create a Gerrit user with that key::
cat ~/id_rsa.pub | ssh -p29418 review.example.com gerrit create-account --ssh-key - --full-name Zuul zuul
.. note:: If you use an RSA key, ensure it is encoded in the PEM
format (use the ``-t rsa -m PEM`` arguments to
`ssh-keygen`).
Give that user whatever permissions will be needed on the projects you
want Zuul to report on. For instance, you may want to grant
``Verified +/-1`` and ``Submit`` to the user. Additional categories
or values may be added to Gerrit. Zuul is very flexible and can take
advantage of those.
If ``change.submitWholeTopic`` is configured in Gerrit, Zuul will
honor this by enqueing changes with the same topic as circular
dependencies. However, it is still necessary to enable circular
dependency support in any pipeline queues where such changes may
appear. See :attr:`queue.allow-circular-dependencies` for information
on how to configure this.
Connection Configuration
------------------------
The supported options in ``zuul.conf`` connections are:
.. attr:: <gerrit connection>
.. attr:: driver
:required:
.. value:: gerrit
The connection must set ``driver=gerrit`` for Gerrit connections.
.. attr:: server
:required:
Fully qualified domain name of Gerrit server.
.. attr:: ssh_server
If SSH access to the Gerrit server should be via a different
hostname than web access, set this value to the hostname to use
for SSH connections.
.. attr:: canonical_hostname
The canonical hostname associated with the git repos on the
Gerrit server. Defaults to the value of
:attr:`<gerrit connection>.server`. This is used to identify
projects from this connection by name and in preparing repos on
the filesystem for use by jobs. Note that Zuul will still only
communicate with the Gerrit server identified by ``server``;
this option is useful if users customarily use a different
hostname to clone or pull git repos so that when Zuul places
them in the job's working directory, they appear under this
directory name.
.. attr:: port
:default: 29418
Gerrit server port.
.. attr:: baseurl
:default: https://{server}
Path to Gerrit web interface. Omit the trailing ``/``.
.. attr:: gitweb_url_template
:default: {baseurl}/gitweb?p={project.name}.git;a=commitdiff;h={sha}
Url template for links to specific git shas. By default this will
point at Gerrit's built in gitweb but you can customize this value
to point elsewhere (like cgit or github).
The three values available for string interpolation are baseurl
which points back to Gerrit, project and all of its safe attributes,
and sha which is the git sha1.
.. attr:: user
:default: zuul
User name to use when logging into Gerrit via ssh.
.. attr:: sshkey
:default: ~zuul/.ssh/id_rsa
Path to SSH key to use when logging into Gerrit.
.. attr:: keepalive
:default: 60
SSH connection keepalive timeout; ``0`` disables.
.. attr:: password
The HTTP authentication password for the user. This is
optional, but if it is provided, Zuul will report to Gerrit via
HTTP rather than SSH. It is required in order for file and line
comments to reported (the Gerrit SSH API only supports review
messages). Retrieve this password from the ``HTTP Password``
section of the ``Settings`` page in Gerrit.
.. attr:: git_over_ssh
:default: false
This forces git operation over SSH even if the ``password``
attribute is set. This allow REST API access to the Gerrit
server even when git-over-http operation is disabled on the
server.
.. attr:: auth_type
:default: basic
The HTTP authentication mechanism.
.. value:: basic
HTTP Basic authentication; the default for most Gerrit
installations.
.. value:: digest
HTTP Digest authentication; only used in versions of Gerrit
prior to 2.15.
.. value:: form
Zuul will submit a username and password to a form in order
to authenticate.
.. value:: gcloud_service
Only valid when running in Google Cloud. This will use the
default service account to authenticate to Gerrit. Note that
this will only be used for interacting with the Gerrit API;
anonymous HTTP access will be used to access the git
repositories, therefore private repos or draft changes will
not be available.
.. attr:: verify_ssl
:default: true
When using a self-signed certificate, this may be set to
``false`` to disable SSL certificate verification.
Trigger Configuration
---------------------
Zuul works with standard versions of Gerrit by invoking the ``gerrit
stream-events`` command over an SSH connection. It also reports back
to Gerrit using SSH.
If using Gerrit 2.7 or later, make sure the user is a member of a group
that is granted the ``Stream Events`` permission, otherwise it will not
be able to invoke the ``gerrit stream-events`` command over SSH.
.. attr:: pipeline.trigger.<gerrit source>
The dictionary passed to the Gerrit pipeline ``trigger`` attribute
supports the following attributes:
.. attr:: event
:required:
The event name from gerrit. Examples: ``patchset-created``,
``comment-added``, ``ref-updated``. This field is treated as a
regular expression.
.. attr:: branch
The branch associated with the event. Example: ``master``.
This field is treated as a regular expression, and multiple
branches may be listed.
.. attr:: ref
On ref-updated events, the branch parameter is not used, instead
the ref is provided. Currently Gerrit has the somewhat
idiosyncratic behavior of specifying bare refs for branch names
(e.g., ``master``), but full ref names for other kinds of refs
(e.g., ``refs/tags/foo``). Zuul matches this value exactly
against what Gerrit provides. This field is treated as a
regular expression, and multiple refs may be listed.
.. attr:: ignore-deletes
:default: true
When a branch is deleted, a ref-updated event is emitted with a
newrev of all zeros specified. The ``ignore-deletes`` field is a
boolean value that describes whether or not these newrevs
trigger ref-updated events.
.. attr:: approval
This is only used for ``comment-added`` events. It only matches
if the event has a matching approval associated with it.
Example: ``Code-Review: 2`` matches a ``+2`` vote on the code
review category. Multiple approvals may be listed.
.. attr:: email
This is used for any event. It takes a regex applied on the
performer email, i.e. Gerrit account email address. If you want
to specify several email filters, you must use a YAML list.
Make sure to use non greedy matchers and to escapes dots!
Example: ``email: ^.*?@example\.org$``.
.. attr:: username
This is used for any event. It takes a regex applied on the
performer username, i.e. Gerrit account name. If you want to
specify several username filters, you must use a YAML list.
Make sure to use non greedy matchers and to escapes dots.
Example: ``username: ^zuul$``.
.. attr:: comment
This is only used for ``comment-added`` events. It accepts a
list of regexes that are searched for in the comment string. If
any of these regexes matches a portion of the comment string the
trigger is matched. ``comment: retrigger`` will match when
comments containing ``retrigger`` somewhere in the comment text
are added to a change.
.. attr:: require-approval
This may be used for any event. It requires that a certain kind
of approval be present for the current patchset of the change
(the approval could be added by the event in question). It
follows the same syntax as :attr:`pipeline.require.<gerrit
source>.approval`. For each specified criteria there must exist
a matching approval.
.. attr:: reject-approval
This takes a list of approvals in the same format as
:attr:`pipeline.trigger.<gerrit source>.require-approval` but
the item will fail to enter the pipeline if there is a matching
approval.
Reporter Configuration
----------------------
Zuul works with standard versions of Gerrit by invoking the ``gerrit``
command over an SSH connection, unless the connection is configured
with an HTTP password, in which case the HTTP API is used.
.. attr:: pipeline.reporter.<gerrit reporter>
The dictionary passed to the Gerrit reporter is used to provide label
values to Gerrit. To set the `Verified` label to `1`, add ``verified:
1`` to the dictionary.
The following additional keys are recognized:
.. attr:: submit
:default: False
Set this to ``True`` to submit (merge) the change.
.. attr:: comment
:default: True
If this is true (the default), Zuul will leave review messages
on the change (including job results). Set this to false to
disable this behavior (file and line commands will still be sent
if present).
A :ref:`connection<connections>` that uses the gerrit driver must be
supplied to the trigger.
Requirements Configuration
--------------------------
As described in :attr:`pipeline.require` and :attr:`pipeline.reject`,
pipelines may specify that items meet certain conditions in order to
be enqueued into the pipeline. These conditions vary according to the
source of the project in question. To supply requirements for changes
from a Gerrit source named ``my-gerrit``, create a configuration such
as the following:
.. code-block:: yaml
pipeline:
require:
my-gerrit:
approval:
- Code-Review: 2
This indicates that changes originating from the Gerrit connection
named ``my-gerrit`` must have a ``Code-Review`` vote of ``+2`` in
order to be enqueued into the pipeline.
.. attr:: pipeline.require.<gerrit source>
The dictionary passed to the Gerrit pipeline `require` attribute
supports the following attributes:
.. attr:: approval
This requires that a certain kind of approval be present for the
current patchset of the change (the approval could be added by
the event in question). Approval is a dictionary or a list of
dictionaries with attributes listed below, all of which are
optional and are combined together so that there must be an approval
matching all specified requirements.
.. attr:: username
If present, an approval from this username is required. It is
treated as a regular expression.
.. attr:: email
If present, an approval with this email address is required. It is
treated as a regular expression.
.. attr:: older-than
If present, the approval must be older than this amount of time
to match. Provide a time interval as a number with a suffix of
"w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
(seconds). Example ``48h`` or ``2d``.
.. attr:: newer-than
If present, the approval must be newer than this amount
of time to match. Same format as "older-than".
Any other field is interpreted as a review category and value
pair. For example ``Verified: 1`` would require that the
approval be for a +1 vote in the "Verified" column. The value
may either be a single value or a list: ``Verified: [1, 2]``
would match either a +1 or +2 vote.
.. attr:: open
A boolean value (``true`` or ``false``) that indicates whether
the change must be open or closed in order to be enqueued.
.. attr:: current-patchset
A boolean value (``true`` or ``false``) that indicates whether the
change must be the current patchset in order to be enqueued.
.. attr:: wip
A boolean value (``true`` or ``false``) that indicates whether the
change must be wip or not wip in order to be enqueued.
.. attr:: status
A string value that corresponds with the status of the change
reported by the trigger.
.. attr:: pipeline.reject.<gerrit source>
The `reject` attribute is the mirror of the `require` attribute. It
also accepts a dictionary under the connection name. This
dictionary supports the following attributes:
.. attr:: approval
This takes an approval or a list of approvals. If an approval
matches the provided criteria the change can not be entered
into the pipeline. It follows the same syntax as
:attr:`pipeline.require.<gerrit source>.approval`.
Example to reject a change with any negative vote:
.. code-block:: yaml
reject:
my-gerrit:
approval:
- Code-Review: [-1, -2]
Reference Pipelines Configuration
---------------------------------
Here is an example of standard pipelines you may want to define:
.. literalinclude:: /examples/pipelines/gerrit-reference-pipelines.yaml
:language: yaml
Checks Plugin Support (Experimental)
------------------------------------
The Gerrit driver has experimental support for Gerrit's `checks`
plugin. Neither the `checks` plugin itself nor Zuul's support for it
are stable yet, and this is not recommended for production use. If
you wish to help develop this support, you should expect to be able to
upgrade both Zuul and Gerrit frequently as the two systems evolve. No
backward-compatible support will be provided and configurations may
need to be updated frequently.
Caveats include (but are not limited to):
* This documentation is brief.
* Access control for the `checks` API in Gerrit depends on a single
global administrative permission, ``administrateCheckers``. This is
required in order to use the `checks` API and can not be restricted
by project. This means that any system using the `checks` API can
interfere with any other.
* Checkers are restricted to a single project. This means that a
system with many projects will require many checkers to be defined
in Gerrit -- one for each project+pipeline.
* No support is provided for attaching checks to tags or commits,
meaning that tag, release, and post pipelines are unable to be used
with the `checks` API and must rely on `stream-events`.
* Sub-checks are not implemented yet, so in order to see the results
of individual jobs on a change, users must either follow the
buildset link, or the pipeline must be configured to leave a
traditional comment.
* Familiarity with the `checks` API is recommended.
* Checkers may not be permanently deleted from Gerrit (only
"soft-deleted" so they no longer apply), so any experiments you
perform on a production system will leave data there forever.
In order to use the `checks` API, you must have HTTP access configured
in `zuul.conf`.
There are two ways to configure a pipeline for the `checks` API:
directly referencing the checker UUID, or referencing it's scheme. It
is hoped that once multi-repository checks are supported, that an
administrator will be able to configure a single checker in Gerrit for
each Zuul pipeline, and those checkers can apply to all repositories.
If and when that happens, we will be able to reference the checker
UUID directly in Zuul's pipeline configuration. If you only have a
single project, you may find this approach acceptable now.
To use this approach, create a checker named ``zuul:check`` and
configure a pipeline like this:
.. code-block:: yaml
- pipeline:
name: check
manager: independent
trigger:
gerrit:
- event: pending-check
uuid: 'zuul:check'
enqueue:
gerrit:
checks-api:
uuid: 'zuul:check'
state: SCHEDULED
message: 'Change has been enqueued in check'
start:
gerrit:
checks-api:
uuid: 'zuul:check'
state: RUNNING
message: 'Jobs have started running'
no-jobs:
gerrit:
checks-api:
uuid: 'zuul:check'
state: NOT_RELEVANT
message: 'Change has no jobs configured'
success:
gerrit:
checks-api:
uuid: 'zuul:check'
state: SUCCESSFUL
message: 'Change passed all voting jobs'
failure:
gerrit:
checks-api:
uuid: 'zuul:check'
state: FAILED
message: 'Change failed'
For a system with multiple repositories and one or more checkers for
each repository, the `scheme` approach is recommended. To use this,
create a checker for each pipeline in each repository. Give them
names such as ``zuul_check:project1``, ``zuul_gate:project1``,
``zuul_check:project2``, etc. The part before the ``:`` is the
`scheme`. Then create a pipeline like this:
.. code-block:: yaml
- pipeline:
name: check
manager: independent
trigger:
gerrit:
- event: pending-check
scheme: 'zuul_check'
enqueue:
gerrit:
checks-api:
scheme: 'zuul_check'
state: SCHEDULED
message: 'Change has been enqueued in check'
start:
gerrit:
checks-api:
scheme: 'zuul_check'
state: RUNNING
message: 'Jobs have started running'
no-jobs:
gerrit:
checks-api:
scheme: 'zuul_check'
state: NOT_RELEVANT
message: 'Change has no jobs configured'
success:
gerrit:
checks-api:
scheme: 'zuul_check'
state: SUCCESSFUL
message: 'Change passed all voting jobs'
failure:
gerrit:
checks-api:
scheme: 'zuul_check'
state: FAILED
message: 'Change failed'
This will match and report to the appropriate checker for a given
repository based on the scheme you provided.
.. The original design doc may be of use during development:
https://gerrit-review.googlesource.com/c/gerrit/+/214733
|