James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 1 | :title: Gerrit Driver |
| 2 | |
| 3 | Gerrit |
| 4 | ====== |
| 5 | |
| 6 | `Gerrit`_ is a code review system. The Gerrit driver supports |
| 7 | sources, triggers, and reporters. |
| 8 | |
| 9 | .. _Gerrit: https://www.gerritcodereview.com/ |
| 10 | |
| 11 | Zuul will need access to a Gerrit user. |
| 12 | |
| 13 | Create an SSH keypair for Zuul to use if there isn't one already, and |
| 14 | create 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 | |
| 18 | Give that user whatever permissions will be needed on the projects you |
| 19 | want Zuul to report on. For instance, you may want to grant |
| 20 | ``Verified +/-1`` and ``Submit`` to the user. Additional categories |
| 21 | or values may be added to Gerrit. Zuul is very flexible and can take |
| 22 | advantage of those. |
| 23 | |
| 24 | Connection Configuration |
| 25 | ------------------------ |
| 26 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 27 | The supported options in ``zuul.conf`` connections are: |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 28 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 29 | .. attr:: <gerrit connection> |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 30 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 31 | .. attr:: driver |
| 32 | :required: |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 33 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 34 | .. value:: gerrit |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 35 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 36 | The connection must set ``driver=gerrit`` for Gerrit connections. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 37 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 38 | .. attr:: server |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 39 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 40 | Fully qualified domain name of Gerrit server. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 41 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 42 | .. attr:: canonical_hostname |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 43 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 44 | The canonical hostname associated with the git repos on the |
| 45 | Gerrit server. Defaults to the value of |
| 46 | :attr:`<gerrit connection>.server`. This is used to identify |
| 47 | projects from this connection by name and in preparing repos on |
| 48 | the filesystem for use by jobs. Note that Zuul will still only |
| 49 | communicate with the Gerrit server identified by ``server``; |
| 50 | this option is useful if users customarily use a different |
| 51 | hostname to clone or pull git repos so that when Zuul places |
| 52 | them in the job's working directory, they appear under this |
| 53 | directory name. |
| 54 | |
| 55 | .. attr:: port |
| 56 | :default: 29418 |
| 57 | |
| 58 | Gerrit server port. |
| 59 | |
| 60 | .. attr:: baseurl |
| 61 | |
| 62 | Path to Gerrit web interface. |
| 63 | |
Clark Boylan | a7f724c | 2017-10-25 11:35:19 -0700 | [diff] [blame] | 64 | .. attr:: gitweb_url_template |
| 65 | :default: {baseurl}/gitweb?p={project.name}.git;a=commitdiff;h={sha} |
| 66 | |
| 67 | Url template for links to specific git shas. By default this will |
| 68 | point at Gerrit's built in gitweb but you can customize this value |
| 69 | to point elsewhere (like cgit or github). |
| 70 | |
| 71 | The three values available for string interpolation are baseurl |
| 72 | which points back to Gerrit, project and all of its safe attributes, |
| 73 | and sha which is the git sha1. |
| 74 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 75 | .. attr:: user |
| 76 | :default: zuul |
| 77 | |
| 78 | User name to use when logging into Gerrit via ssh. |
| 79 | |
| 80 | .. attr:: sshkey |
| 81 | :default: ~zuul/.ssh/id_rsa |
| 82 | |
| 83 | Path to SSH key to use when logging into Gerrit. |
| 84 | |
| 85 | .. attr:: keepalive |
| 86 | :default: 60 |
| 87 | |
| 88 | SSH connection keepalive timeout; ``0`` disables. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 89 | |
| 90 | Trigger Configuration |
| 91 | --------------------- |
| 92 | |
| 93 | Zuul works with standard versions of Gerrit by invoking the ``gerrit |
| 94 | stream-events`` command over an SSH connection. It also reports back |
| 95 | to Gerrit using SSH. |
| 96 | |
| 97 | If using Gerrit 2.7 or later, make sure the user is a member of a group |
| 98 | that is granted the ``Stream Events`` permission, otherwise it will not |
| 99 | be able to invoke the ``gerrit stream-events`` command over SSH. |
| 100 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 101 | .. attr:: pipeline.trigger.<gerrit source> |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 102 | |
James E. Blair | 02157ad | 2017-08-03 17:34:22 -0700 | [diff] [blame] | 103 | The dictionary passed to the Gerrit pipeline ``trigger`` attribute |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 104 | supports the following attributes: |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 105 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 106 | .. attr:: event |
| 107 | :required: |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 108 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 109 | The event name from gerrit. Examples: ``patchset-created``, |
| 110 | ``comment-added``, ``ref-updated``. This field is treated as a |
| 111 | regular expression. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 112 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 113 | .. attr:: branch |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 114 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 115 | The branch associated with the event. Example: ``master``. |
| 116 | This field is treated as a regular expression, and multiple |
| 117 | branches may be listed. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 118 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 119 | .. attr:: ref |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 120 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 121 | On ref-updated events, the branch parameter is not used, instead |
| 122 | the ref is provided. Currently Gerrit has the somewhat |
| 123 | idiosyncratic behavior of specifying bare refs for branch names |
| 124 | (e.g., ``master``), but full ref names for other kinds of refs |
| 125 | (e.g., ``refs/tags/foo``). Zuul matches this value exactly |
| 126 | against what Gerrit provides. This field is treated as a |
| 127 | regular expression, and multiple refs may be listed. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 128 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 129 | .. attr:: ignore-deletes |
| 130 | :default: true |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 131 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 132 | When a branch is deleted, a ref-updated event is emitted with a |
| 133 | newrev of all zeros specified. The ``ignore-deletes`` field is a |
| 134 | boolean value that describes whether or not these newrevs |
| 135 | trigger ref-updated events. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 136 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 137 | .. attr:: approval |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 138 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 139 | This is only used for ``comment-added`` events. It only matches |
| 140 | if the event has a matching approval associated with it. |
| 141 | Example: ``Code-Review: 2`` matches a ``+2`` vote on the code |
| 142 | review category. Multiple approvals may be listed. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 143 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 144 | .. attr:: email |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 145 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 146 | This is used for any event. It takes a regex applied on the |
| 147 | performer email, i.e. Gerrit account email address. If you want |
| 148 | to specify several email filters, you must use a YAML list. |
| 149 | Make sure to use non greedy matchers and to escapes dots! |
| 150 | Example: ``email: ^.*?@example\.org$``. |
| 151 | |
| 152 | .. attr:: username |
| 153 | |
| 154 | This is used for any event. It takes a regex applied on the |
| 155 | performer username, i.e. Gerrit account name. If you want to |
| 156 | specify several username filters, you must use a YAML list. |
| 157 | Make sure to use non greedy matchers and to escapes dots. |
| 158 | Example: ``username: ^zuul$``. |
| 159 | |
| 160 | .. attr:: comment |
| 161 | |
| 162 | This is only used for ``comment-added`` events. It accepts a |
| 163 | list of regexes that are searched for in the comment string. If |
| 164 | any of these regexes matches a portion of the comment string the |
| 165 | trigger is matched. ``comment: retrigger`` will match when |
| 166 | comments containing ``retrigger`` somewhere in the comment text |
| 167 | are added to a change. |
| 168 | |
| 169 | .. attr:: require-approval |
| 170 | |
| 171 | This may be used for any event. It requires that a certain kind |
| 172 | of approval be present for the current patchset of the change |
| 173 | (the approval could be added by the event in question). It |
| 174 | follows the same syntax as :attr:`pipeline.require.<gerrit |
| 175 | source>.approval`. For each specified criteria there must exist |
| 176 | a matching approval. |
| 177 | |
| 178 | .. attr:: reject-approval |
| 179 | |
| 180 | This takes a list of approvals in the same format as |
| 181 | :attr:`pipeline.trigger.<gerrit source>.require-approval` but |
| 182 | will fail to enter the pipeline if there is a matching approval. |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 183 | |
| 184 | Reporter Configuration |
| 185 | ---------------------- |
| 186 | |
| 187 | Zuul works with standard versions of Gerrit by invoking the |
| 188 | ``gerrit`` command over an SSH connection. It reports back to |
| 189 | Gerrit using SSH. |
| 190 | |
| 191 | The dictionary passed to the Gerrit reporter is used for ``gerrit |
| 192 | review`` arguments, with the boolean value of ``true`` simply |
| 193 | indicating that the argument should be present without following it |
| 194 | with a value. For example, ``verified: 1`` becomes ``gerrit review |
| 195 | --verified 1`` and ``submit: true`` becomes ``gerrit review |
| 196 | --submit``. |
| 197 | |
| 198 | A :ref:`connection<connections>` that uses the gerrit driver must be |
| 199 | supplied to the trigger. |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 200 | |
| 201 | Requirements Configuration |
| 202 | -------------------------- |
| 203 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 204 | As described in :attr:`pipeline.require` and :attr:`pipeline.reject`, |
| 205 | pipelines may specify that items meet certain conditions in order to |
| 206 | be enqueued into the pipeline. These conditions vary according to the |
| 207 | source of the project in question. To supply requirements for changes |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 208 | from a Gerrit source named ``my-gerrit``, create a configuration such |
| 209 | as the following: |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 210 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 211 | .. code-block:: yaml |
| 212 | |
| 213 | pipeline: |
| 214 | require: |
| 215 | my-gerrit: |
| 216 | approval: |
| 217 | - Code-Review: 2 |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 218 | |
| 219 | This indicates that changes originating from the Gerrit connection |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 220 | named ``my-gerrit`` must have a ``Code-Review`` vote of ``+2`` in |
| 221 | order to be enqueued into the pipeline. |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 222 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 223 | .. attr:: pipeline.require.<gerrit source> |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 224 | |
| 225 | The dictionary passed to the Gerrit pipeline `require` attribute |
| 226 | supports the following attributes: |
| 227 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 228 | .. attr:: approval |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 229 | |
| 230 | This requires that a certain kind of approval be present for the |
| 231 | current patchset of the change (the approval could be added by |
| 232 | the event in question). It takes several sub-parameters, all of |
| 233 | which are optional and are combined together so that there must |
| 234 | be an approval matching all specified requirements. |
| 235 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 236 | .. attr:: username |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 237 | |
| 238 | If present, an approval from this username is required. It is |
| 239 | treated as a regular expression. |
| 240 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 241 | .. attr:: email |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 242 | |
| 243 | If present, an approval with this email address is required. It is |
| 244 | treated as a regular expression. |
| 245 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 246 | .. attr:: older-than |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 247 | |
| 248 | If present, the approval must be older than this amount of time |
| 249 | to match. Provide a time interval as a number with a suffix of |
| 250 | "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s" |
| 251 | (seconds). Example ``48h`` or ``2d``. |
| 252 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 253 | .. attr:: newer-than |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 254 | |
| 255 | If present, the approval must be newer than this amount |
| 256 | of time to match. Same format as "older-than". |
| 257 | |
| 258 | Any other field is interpreted as a review category and value |
| 259 | pair. For example ``Verified: 1`` would require that the |
| 260 | approval be for a +1 vote in the "Verified" column. The value |
| 261 | may either be a single value or a list: ``Verified: [1, 2]`` |
| 262 | would match either a +1 or +2 vote. |
| 263 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 264 | .. attr:: open |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 265 | |
| 266 | A boolean value (``true`` or ``false``) that indicates whether |
| 267 | the change must be open or closed in order to be enqueued. |
| 268 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 269 | .. attr:: current-patchset |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 270 | |
| 271 | A boolean value (``true`` or ``false``) that indicates whether the |
| 272 | change must be the current patchset in order to be enqueued. |
| 273 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 274 | .. attr:: status |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 275 | |
| 276 | A string value that corresponds with the status of the change |
| 277 | reported by the trigger. |
| 278 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 279 | .. attr:: pipeline.reject.<gerrit source> |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 280 | |
| 281 | The `reject` attribute is the mirror of the `require` attribute. It |
| 282 | also accepts a dictionary under the connection name. This |
| 283 | dictionary supports the following attributes: |
| 284 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 285 | .. attr:: approval |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 286 | |
| 287 | This takes a list of approvals. If an approval matches the |
| 288 | provided criteria the change can not be entered into the |
James E. Blair | 91fe483 | 2017-07-28 17:28:26 -0700 | [diff] [blame] | 289 | pipeline. It follows the same syntax as |
| 290 | :attr:`pipeline.require.<gerrit source>.approval`. |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 291 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 292 | Example to reject a change with any negative vote: |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 293 | |
James E. Blair | d23f45d | 2017-08-03 16:37:13 -0700 | [diff] [blame] | 294 | .. code-block:: yaml |
| 295 | |
| 296 | reject: |
| 297 | my-gerrit: |
| 298 | approval: |
| 299 | - Code-Review: [-1, -2] |