blob: e46bb631175cfe26bc3ff05f042303c694f84dbd [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Gerrit Driver
2
3Gerrit
4======
5
6`Gerrit`_ is a code review system. The Gerrit driver supports
7sources, triggers, and reporters.
8
9.. _Gerrit: https://www.gerritcodereview.com/
10
11Zuul will need access to a Gerrit user.
12
13Create an SSH keypair for Zuul to use if there isn't one already, and
14create a Gerrit user with that key::
15
16 cat ~/id_rsa.pub | ssh -p29418 review.example.com gerrit create-account --ssh-key - --full-name Zuul zuul
17
18Give that user whatever permissions will be needed on the projects you
19want Zuul to report on. For instance, you may want to grant
20``Verified +/-1`` and ``Submit`` to the user. Additional categories
21or values may be added to Gerrit. Zuul is very flexible and can take
22advantage of those.
23
24Connection Configuration
25------------------------
26
27The supported options in zuul.conf connections are:
28
29**driver=gerrit**
30
31**server**
32 FQDN of Gerrit server.
33 ``server=review.example.com``
34
35**canonical_hostname**
36 The canonical hostname associated with the git repos on the Gerrit
37 server. Defaults to the value of **server**. This is used to
James E. Blaircc3ca7d2017-06-29 11:09:18 -070038 identify projects from this connection by name and in preparing
39 repos on the filesystem for use by jobs. Note that Zuul will still
40 only communicate with the Gerrit server identified by **server**;
41 this option is useful if users customarily use a different hostname
42 to clone or pull git repos so that when Zuul places them in the
43 job's working directory, they appear under this directory name.
James E. Blaireff5a9d2017-06-20 00:00:37 -070044 ``canonical_hostname=git.example.com``
45
46**port**
47 Optional: Gerrit server port.
48 ``port=29418``
49
50**baseurl**
51 Optional: path to Gerrit web interface. Defaults to ``https://<value
52 of server>/``. ``baseurl=https://review.example.com/review_site/``
53
54**user**
55 User name to use when logging into above server via ssh.
56 ``user=zuul``
57
58**sshkey**
59 Path to SSH key to use when logging into above server.
60 ``sshkey=/home/zuul/.ssh/id_rsa``
61
62**keepalive**
63 Optional: Keepalive timeout, 0 means no keepalive.
64 ``keepalive=60``
65
66Trigger Configuration
67---------------------
68
69Zuul works with standard versions of Gerrit by invoking the ``gerrit
70stream-events`` command over an SSH connection. It also reports back
71to Gerrit using SSH.
72
73If using Gerrit 2.7 or later, make sure the user is a member of a group
74that is granted the ``Stream Events`` permission, otherwise it will not
75be able to invoke the ``gerrit stream-events`` command over SSH.
76
77The supported pipeline trigger options are:
78
79**event**
James E. Blair88e53882017-06-23 21:45:07 +010080 The event name from gerrit. Examples: ``patchset-created``,
81 ``comment-added``, ``ref-updated``. This field is treated as a
82 regular expression.
James E. Blaireff5a9d2017-06-20 00:00:37 -070083
84**branch**
James E. Blair88e53882017-06-23 21:45:07 +010085 The branch associated with the event. Example: ``master``. This
86 field is treated as a regular expression, and multiple branches may
87 be listed.
James E. Blaireff5a9d2017-06-20 00:00:37 -070088
89**ref**
James E. Blair88e53882017-06-23 21:45:07 +010090 On ref-updated events, the branch parameter is not used, instead the
91 ref is provided. Currently Gerrit has the somewhat idiosyncratic
92 behavior of specifying bare refs for branch names (e.g.,
93 ``master``), but full ref names for other kinds of refs (e.g.,
94 ``refs/tags/foo``). Zuul matches what you put here exactly against
95 what Gerrit provides. This field is treated as a regular
96 expression, and multiple refs may be listed.
James E. Blaireff5a9d2017-06-20 00:00:37 -070097
98**ignore-deletes**
James E. Blair88e53882017-06-23 21:45:07 +010099 When a branch is deleted, a ref-updated event is emitted with a
100 newrev of all zeros specified. The ``ignore-deletes`` field is a
101 boolean value that describes whether or not these newrevs trigger
102 ref-updated events. The default is True, which will not trigger
103 ref-updated events.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700104
105**approval**
James E. Blair88e53882017-06-23 21:45:07 +0100106 This is only used for ``comment-added`` events. It only matches if
107 the event has a matching approval associated with it. Example:
108 ``code-review: 2`` matches a ``+2`` vote on the code review
109 category. Multiple approvals may be listed.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700110
111**email**
James E. Blair88e53882017-06-23 21:45:07 +0100112 This is used for any event. It takes a regex applied on the
113 performer email, i.e. Gerrit account email address. If you want to
114 specify several email filters, you must use a YAML list. Make sure
115 to use non greedy matchers and to escapes dots! Example: ``email:
116 ^.*?@example\.org$``.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700117
118**email_filter** (deprecated)
James E. Blair88e53882017-06-23 21:45:07 +0100119 A deprecated alternate spelling of *email*. Only one of *email* or
120 *email_filter* should be used.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700121
122**username**
James E. Blair88e53882017-06-23 21:45:07 +0100123 This is used for any event. It takes a regex applied on the
124 performer username, i.e. Gerrit account name. If you want to
125 specify several username filters, you must use a YAML list. Make
126 sure to use non greedy matchers and to escapes dots! Example:
127 ``username: ^jenkins$``.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700128
129**username_filter** (deprecated)
James E. Blair88e53882017-06-23 21:45:07 +0100130 A deprecated alternate spelling of *username*. Only one of
131 *username* or *username_filter* should be used.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700132
133**comment**
James E. Blair88e53882017-06-23 21:45:07 +0100134 This is only used for ``comment-added`` events. It accepts a list
135 of regexes that are searched for in the comment string. If any of
136 these regexes matches a portion of the comment string the trigger is
137 matched. ``comment: retrigger`` will match when comments containing
138 'retrigger' somewhere in the comment text are added to a change.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700139
140**comment_filter** (deprecated)
James E. Blair88e53882017-06-23 21:45:07 +0100141 A deprecated alternate spelling of *comment*. Only one of *comment*
142 or *comment_filter* should be used.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700143
James E. Blair88e53882017-06-23 21:45:07 +0100144**require-approval**
145 This may be used for any event. It requires that a certain kind of
146 approval be present for the current patchset of the change (the
147 approval could be added by the event in question). It follows the
148 same syntax as the :ref:`"approval" pipeline requirement
James E. Blaird134c6d2017-07-26 16:09:34 -0700149 <gerrit-pipeline-require-approval>`. For each specified criteria
150 there must exist a matching approval.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700151
James E. Blair88e53882017-06-23 21:45:07 +0100152**reject-approval**
153 This takes a list of approvals in the same format as
154 *require-approval* but will fail to enter the pipeline if there is a
155 matching approval.
James E. Blaireff5a9d2017-06-20 00:00:37 -0700156
157Reporter Configuration
158----------------------
159
160Zuul works with standard versions of Gerrit by invoking the
161``gerrit`` command over an SSH connection. It reports back to
162Gerrit using SSH.
163
164The dictionary passed to the Gerrit reporter is used for ``gerrit
165review`` arguments, with the boolean value of ``true`` simply
166indicating that the argument should be present without following it
167with a value. For example, ``verified: 1`` becomes ``gerrit review
168--verified 1`` and ``submit: true`` becomes ``gerrit review
169--submit``.
170
171A :ref:`connection<connections>` that uses the gerrit driver must be
172supplied to the trigger.
James E. Blaird134c6d2017-07-26 16:09:34 -0700173
174Requirements Configuration
175--------------------------
176
177As described in :ref:`pipeline.require <pipeline-require>` and
178:ref:`pipeline.reject <pipeline-reject>`, pipelines may specify that
179items meet certain conditions in order to be enqueued into the
180pipeline. These conditions vary according to the source of the
181project in question. To supply requirements for changes from a Gerrit
182source named *my-gerrit*, create a congfiguration such as the
183following::
184
185 pipeline:
186 require:
187 my-gerrit:
188 approval:
189 - code-review: 2
190
191This indicates that changes originating from the Gerrit connection
192named *my-gerrit* must have a Code Review vote of +2 in order to be
193enqueued into the pipeline.
194
195.. zuul:configobject:: pipeline.require.<source>
196
197 The dictionary passed to the Gerrit pipeline `require` attribute
198 supports the following attributes:
199
200 .. _gerrit-pipeline-require-approval:
201
202 .. zuul:attr:: approval
203
204 This requires that a certain kind of approval be present for the
205 current patchset of the change (the approval could be added by
206 the event in question). It takes several sub-parameters, all of
207 which are optional and are combined together so that there must
208 be an approval matching all specified requirements.
209
210 .. zuul:attr:: username
211
212 If present, an approval from this username is required. It is
213 treated as a regular expression.
214
215 .. zuul:attr:: email
216
217 If present, an approval with this email address is required. It is
218 treated as a regular expression.
219
220 .. zuul:attr:: older-than
221
222 If present, the approval must be older than this amount of time
223 to match. Provide a time interval as a number with a suffix of
224 "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
225 (seconds). Example ``48h`` or ``2d``.
226
227 .. zuul:attr:: newer-than
228
229 If present, the approval must be newer than this amount
230 of time to match. Same format as "older-than".
231
232 Any other field is interpreted as a review category and value
233 pair. For example ``Verified: 1`` would require that the
234 approval be for a +1 vote in the "Verified" column. The value
235 may either be a single value or a list: ``Verified: [1, 2]``
236 would match either a +1 or +2 vote.
237
238 .. zuul:attr:: open
239
240 A boolean value (``true`` or ``false``) that indicates whether
241 the change must be open or closed in order to be enqueued.
242
243 .. zuul:attr:: current-patchset
244
245 A boolean value (``true`` or ``false``) that indicates whether the
246 change must be the current patchset in order to be enqueued.
247
248 .. zuul:attr:: status
249
250 A string value that corresponds with the status of the change
251 reported by the trigger.
252
253.. zuul:configobject:: pipeline.reject.<source>
254
255 The `reject` attribute is the mirror of the `require` attribute. It
256 also accepts a dictionary under the connection name. This
257 dictionary supports the following attributes:
258
259 .. zuul:attr:: approval
260
261 This takes a list of approvals. If an approval matches the
262 provided criteria the change can not be entered into the
263 pipeline. It follows the same syntax as the :ref:`approval
264 pipeline requirement above <gerrit-pipeline-require-approval>`.
265
266 Example to reject a change with any negative vote::
267
268 reject:
269 my-gerrit:
270 approval:
271 - code-review: [-1, -2]