Separate reporters from triggers
Allows multiple reports per a patchset to be sent to pluggable
destinations. These are configurable per pipeline and, if not
specified, defaults to the legacy behaviour of reporting back only
to gerrit.
Having multiple reporting methods means only certain success/failure
/start parameters will apply to certain reporters. Reporters are
listed as keys under each of those actions.
This means that each key under success/failure/start is a reporter and the
dictionaries under those are sent to the reporter to deal with.
Change-Id: I80d7539772e1485d5880132f22e55751b25ec198
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 039cffa..5a0c7b9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -21,6 +21,7 @@
gating
triggers
launchers
+ reporters
zuul
Indices and tables
diff --git a/doc/source/reporters.rst b/doc/source/reporters.rst
new file mode 100644
index 0000000..d64d4f7
--- /dev/null
+++ b/doc/source/reporters.rst
@@ -0,0 +1,32 @@
+:title: Reporters
+
+Reporters
+=========
+
+Zuul can communicate results and progress back to configurable
+protocols. For example, after succeeding in a build a pipeline can be
+configured to post a positive review back to gerrit.
+
+There are three stages when a report can be handled. That is on:
+Start, Success or Failure. Each stage can have multiple reports.
+For example, you can set verified on gerrit and send an email.
+
+Gerrit
+------
+
+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``.
+
+Gerrit Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+The configuration for posting back to gerrit is shared with the gerrit
+trigger in zuul.conf. Please consult the gerrit trigger documentation.
diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst
index f5e2226..91ac24a 100644
--- a/doc/source/zuul.rst
+++ b/doc/source/zuul.rst
@@ -338,16 +338,14 @@
the change, set this to ``false``. Default: ``true``.
**success**
- Describes what Zuul should do if all the jobs complete successfully.
+ Describes where Zuul should report to if all the jobs complete
+ successfully.
This section is optional; if it is omitted, Zuul will run jobs and
do nothing on success; it will not even report a message to Gerrit.
- If the section is present, it will leave a message on the Gerrit
- review. Each additional argument is assumed to be an argument to
- ``gerrit review``, 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``.
+ If the section is present, the listed reporter plugins will be
+ asked to report on the jobs.
+ Each reporter's value dictionary is handled by the reporter. See
+ reporters for more details.
**failure**
Uses the same syntax as **success**, but describes what Zuul should
@@ -373,9 +371,11 @@
trigger:
- event: patchset-created
success:
- verified: 1
+ gerrit:
+ verified: 1
failure:
- verified: -1
+ gerrit:
+ verified: -1
This will trigger jobs each time a new patchset (or change) is
uploaded to Gerrit, and report +/-1 values to Gerrit in the
@@ -388,10 +388,12 @@
approval:
- approved: 1
success:
- verified: 2
- submit: true
+ gerrit:
+ verified: 2
+ submit: true
failure:
- verified: -2
+ gerrit:
+ verified: -2
This will trigger jobs whenever a reviewer leaves a vote of ``1`` in the
``approved`` review category in Gerrit (a non-standard category).
@@ -425,9 +427,11 @@
trigger:
- event: change-merged
success:
- force-message: True
+ gerrit:
+ force-message: True
failure:
- force-message: True
+ gerrit:
+ force-message: True
The ``change-merged`` events happen when a change has been merged in the git
repository. The change is thus closed and Gerrit will not accept modifications