blob: 29e136be6476d5dd15281a841419f88b22ac5451 [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
149 <pipeline-require-approval>`. For each specified criteria there must
150 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.