Reorganize docs into user/admin guide
Refresh the user and admin guide for v3 changes, and reorganize into
a narrative structure which makes more sense for v3.
Change-Id: I4ac3b18d5ed33b0fea4e2ef0318b19bfc3447ccc
diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
new file mode 100644
index 0000000..6cd2f3d
--- /dev/null
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -0,0 +1,168 @@
+: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.
+ ``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.