doc/source/admin/drivers/gerrit.rst

: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

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.

Connection Configuration
------------------------

The supported options in zuul.conf connections are:

**driver=gerrit**

**server**
  FQDN of Gerrit server.
  ``server=review.example.com``

**canonical_hostname**
  The canonical hostname associated with the git repos on the Gerrit
  server.  Defaults to the value of **server**.  This is used to
  identify repos from this connection by name and in preparing repos
  on the filesystem for use by jobs.  This only needs to be set in the
  case where the canonical public location of the git repos is not the
  same as the Gerrit server and it would be incorrect to refer to
  those repos in configuration and build scripts using the Gerrit
  server hostname.
  ``canonical_hostname=git.example.com``

**port**
  Optional: Gerrit server port.
  ``port=29418``

**baseurl**
  Optional: path to Gerrit web interface. Defaults to ``https://<value
  of server>/``. ``baseurl=https://review.example.com/review_site/``

**user**
  User name to use when logging into above server via ssh.
  ``user=zuul``

**sshkey**
  Path to SSH key to use when logging into above server.
  ``sshkey=/home/zuul/.ssh/id_rsa``

**keepalive**
  Optional: Keepalive timeout, 0 means no keepalive.
  ``keepalive=60``

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.

The supported pipeline trigger options are:

**event**
  The event name from gerrit.  Examples: ``patchset-created``,
  ``comment-added``, ``ref-updated``.  This field is treated as a
  regular expression.

**branch**
  The branch associated with the event.  Example: ``master``.  This
  field is treated as a regular expression, and multiple branches may
  be listed.

**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 what you put here exactly against
  what Gerrit provides.  This field is treated as a regular
  expression, and multiple refs may be listed.

**ignore-deletes**
  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.  The default is True, which will not trigger
  ref-updated events.

**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.

**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$``.

**email_filter** (deprecated)
  A deprecated alternate spelling of *email*.  Only one of *email* or
  *email_filter* should be used.

**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: ^jenkins$``.

**username_filter** (deprecated)
  A deprecated alternate spelling of *username*.  Only one of
  *username* or *username_filter* should be used.

**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.

**comment_filter** (deprecated)
  A deprecated alternate spelling of *comment*.  Only one of *comment*
  or *comment_filter* should be used.

**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 the :ref:`"approval" pipeline requirement
  <pipeline-require-approval>`. For each specified criteria there must
  exist a matching approval.

**reject-approval**
  This takes a list of approvals in the same format as
  *require-approval* but 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.  It reports back to
Gerrit using SSH.

The dictionary passed to the Gerrit reporter is used for ``gerrit
review`` arguments, with the boolean value of ``true`` simply
indicating that the argument should be present without following it
with a value. For example, ``verified: 1`` becomes ``gerrit review
--verified 1`` and ``submit: true`` becomes ``gerrit review
--submit``.

A :ref:`connection<connections>` that uses the gerrit driver must be
supplied to the trigger.