Add GitHub pipeline trigger requirements

This mimics a useful feature of the Gerrit driver and allows users
to configure pipelines that trigger on events but only if certain
conditions of the PR are met.

Unlike the Gerrit driver, this embeds the entire require/reject
filter within the trigger filter (the trigger filter has-a require
or reject filter).  This makes the code simpler and is easier for
users to configure.  If we like this approach, we should migrate the
gerrit driver as well, and perhaps the other drivers.

The "require-status" attribute already existed, but was undocumented.
This documents it, adds backwards-compat handling for it, and
deprecates it.

Some documentation typos are also corrected.

Change-Id: I4b6dd8c970691b1e74ffd5a96c2be4b8075f1a87

1 files changed, 35 insertions, 1 deletions

diff --git a/doc/source/drivers/github.rst b/doc/source/drivers/github.rst
index 148c6f976..7cacf45ac 100644
--- a/doc/source/drivers/github.rst
+++ b/doc/source/drivers/github.rst
@@ -339,7 +339,7 @@ the following options.
       format of ``user:context:status``.  For example,
       ``zuul_github_ci_bot:check_pipeline:success``.
 
-   .. attr: check
+   .. attr:: check
 
       This is only used for ``check_run`` events. It works similar to
       the ``status`` attribute and accepts a list of strings each of
@@ -363,6 +363,38 @@ the following options.
       always sends full ref name, eg. ``refs/tags/bar`` and this
       string is matched against the regular expression.
 
+   .. attr:: require-status
+
+      .. warning:: This is deprecated and will be removed in a future
+                   version.  Use :attr:`pipeline.trigger.<github
+                   source>.require` instead.
+
+      This may be used for any event.  It requires that a certain kind
+      of status be present for the PR (the status could be added by
+      the event in question).  It follows the same syntax as
+      :attr:`pipeline.require.<github source>.status`. For each
+      specified criteria there must exist a matching status.
+
+      This is ignored if the :attr:`pipeline.trigger.<github
+      source>.require` attribute is present.
+
+   .. attr:: require
+
+      This may be used for any event.  It describes conditions that
+      must be met by the PR in order for the trigger event to match.
+      Those conditions may be satisfied by the event in question.  It
+      follows the same syntax as :ref:`github_requirements`.
+
+   .. attr:: reject
+
+      This may be used for any event and is the mirror of
+      :attr:`pipeline.trigger.<github source>.require`.  It describes
+      conditions that when met by the PR cause the trigger event not
+      to match.  Those conditions may be satisfied by the event in
+      question.  It follows the same syntax as
+      :ref:`github_requirements`.
+
+
 Reporter Configuration
 ----------------------
 Zuul reports back to GitHub via GitHub API. Available reports include a PR
@@ -462,6 +494,8 @@ itself. Status name, description, and context is taken from the pipeline.
 
 .. _Github App: https://developer.github.com/apps/
 
+.. _github_requirements:
+
 Requirements Configuration
 --------------------------