Merge "Docs: reformat gerrit driver docs" into feature/zuulv3
This commit is contained in:
Jenkins
Gerrit Code Review
commit
36dd02ac07
|
|
@ -24,44 +24,57 @@ advantage of those.
|
|||
Connection Configuration
|
||||
------------------------
|
||||
|
||||
The supported options in zuul.conf connections are:
|
||||
The supported options in ``zuul.conf`` connections are:
|
||||
|
||||
**driver=gerrit**
|
||||
.. attr:: <gerrit connection>
|
||||
|
||||
**server**
|
||||
FQDN of Gerrit server.
|
||||
``server=review.example.com``
|
||||
.. attr:: driver
|
||||
:required:
|
||||
|
||||
**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 projects from this connection by name and in preparing
|
||||
repos on the filesystem for use by jobs. Note that Zuul will still
|
||||
only communicate with the Gerrit server identified by **server**;
|
||||
this option is useful if users customarily use a different hostname
|
||||
to clone or pull git repos so that when Zuul places them in the
|
||||
job's working directory, they appear under this directory name.
|
||||
``canonical_hostname=git.example.com``
|
||||
.. value:: gerrit
|
||||
|
||||
**port**
|
||||
Optional: Gerrit server port.
|
||||
``port=29418``
|
||||
The connection must set ``driver=gerrit`` for Gerrit connections.
|
||||
|
||||
**baseurl**
|
||||
Optional: path to Gerrit web interface. Defaults to ``https://<value
|
||||
of server>/``. ``baseurl=https://review.example.com/review_site/``
|
||||
.. attr:: server
|
||||
|
||||
**user**
|
||||
User name to use when logging into above server via ssh.
|
||||
``user=zuul``
|
||||
Fully qualified domain name of Gerrit server.
|
||||
|
||||
**sshkey**
|
||||
Path to SSH key to use when logging into above server.
|
||||
``sshkey=/home/zuul/.ssh/id_rsa``
|
||||
.. attr:: canonical_hostname
|
||||
|
||||
**keepalive**
|
||||
Optional: Keepalive timeout, 0 means no keepalive.
|
||||
``keepalive=60``
|
||||
The canonical hostname associated with the git repos on the
|
||||
Gerrit server. Defaults to the value of
|
||||
:attr:`<gerrit connection>.server`. This is used to identify
|
||||
projects from this connection by name and in preparing repos on
|
||||
the filesystem for use by jobs. Note that Zuul will still only
|
||||
communicate with the Gerrit server identified by ``server``;
|
||||
this option is useful if users customarily use a different
|
||||
hostname to clone or pull git repos so that when Zuul places
|
||||
them in the job's working directory, they appear under this
|
||||
directory name.
|
||||
|
||||
.. attr:: port
|
||||
:default: 29418
|
||||
|
||||
Gerrit server port.
|
||||
|
||||
.. attr:: baseurl
|
||||
|
||||
Path to Gerrit web interface.
|
||||
|
||||
.. attr:: user
|
||||
:default: zuul
|
||||
|
||||
User name to use when logging into Gerrit via ssh.
|
||||
|
||||
.. attr:: sshkey
|
||||
:default: ~zuul/.ssh/id_rsa
|
||||
|
||||
Path to SSH key to use when logging into Gerrit.
|
||||
|
||||
.. attr:: keepalive
|
||||
:default: 60
|
||||
|
||||
SSH connection keepalive timeout; ``0`` disables.
|
||||
|
||||
Trigger Configuration
|
||||
---------------------
|
||||
|
|
@ -74,85 +87,88 @@ 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:
|
||||
.. attr:: pipeline.trigger.<gerrit source>
|
||||
|
||||
The dictionary passed to the Gerrit pipeline `trigger` attribute
|
||||
supports the following attributes:
|
||||
|
||||
.. attr:: event
|
||||
:required:
|
||||
|
||||
**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.
|
||||
.. attr:: branch
|
||||
|
||||
**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.
|
||||
The branch associated with the event. Example: ``master``.
|
||||
This field is treated as a regular expression, and multiple
|
||||
branches may be listed.
|
||||
|
||||
.. attr:: 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 this value exactly
|
||||
against what Gerrit provides. This field is treated as a
|
||||
regular expression, and multiple refs may be listed.
|
||||
|
||||
.. attr:: ignore-deletes
|
||||
:default: true
|
||||
|
||||
**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.
|
||||
boolean value that describes whether or not these newrevs
|
||||
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.
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: email
|
||||
|
||||
**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$``.
|
||||
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.
|
||||
.. attr:: username
|
||||
|
||||
**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$``.
|
||||
specify several username filters, you must use a YAML list.
|
||||
Make sure to use non greedy matchers and to escapes dots.
|
||||
Example: ``username: ^zuul$``.
|
||||
|
||||
**username_filter** (deprecated)
|
||||
A deprecated alternate spelling of *username*. Only one of
|
||||
*username* or *username_filter* should be used.
|
||||
.. attr:: comment
|
||||
|
||||
**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.
|
||||
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.
|
||||
.. attr:: require-approval
|
||||
|
||||
**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 :attr:`pipeline.require.<gerrit
|
||||
source>.approval`. For each specified criteria there must exist a
|
||||
matching 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 :attr:`pipeline.require.<gerrit
|
||||
source>.approval`. For each specified criteria there must exist
|
||||
a matching approval.
|
||||
|
||||
.. attr:: reject-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.
|
||||
:attr:`pipeline.trigger.<gerrit source>.require-approval` but
|
||||
will fail to enter the pipeline if there is a matching approval.
|
||||
|
||||
Reporter Configuration
|
||||
----------------------
|
||||
|
|
@ -178,8 +194,10 @@ As described in :attr:`pipeline.require` and :attr:`pipeline.reject`,
|
|||
pipelines may specify that items meet certain conditions in order to
|
||||
be enqueued into the pipeline. These conditions vary according to the
|
||||
source of the project in question. To supply requirements for changes
|
||||
from a Gerrit source named *my-gerrit*, create a configuration such as
|
||||
the following::
|
||||
from a Gerrit source named ``my-gerrit``, create a configuration such
|
||||
as the following:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
pipeline:
|
||||
require:
|
||||
|
|
@ -188,8 +206,8 @@ the following::
|
|||
- Code-Review: 2
|
||||
|
||||
This indicates that changes originating from the Gerrit connection
|
||||
named *my-gerrit* must have a Code Review vote of +2 in order to be
|
||||
enqueued into the pipeline.
|
||||
named ``my-gerrit`` must have a ``Code-Review`` vote of ``+2`` in
|
||||
order to be enqueued into the pipeline.
|
||||
|
||||
.. attr:: pipeline.require.<gerrit source>
|
||||
|
||||
|
|
@ -260,7 +278,9 @@ enqueued into the pipeline.
|
|||
pipeline. It follows the same syntax as
|
||||
:attr:`pipeline.require.<gerrit source>.approval`.
|
||||
|
||||
Example to reject a change with any negative vote::
|
||||
Example to reject a change with any negative vote:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
reject:
|
||||
my-gerrit:
|
||||
|
|
|
|||
Loading…
Reference in New Issue