zuul
/
zuul
Code Issues Proposed changes

Cleanup pipeline requirements 

Pipeline requirements are now per-source.  Remove dead validation
code in configloader which appeared to validate the old form (but
was actually overriden).  Remove requirements from the zuul trigger
which are not used.  Move the current requirements documentation
into the gerrit driver docs, and create github requirements docs.

Change-Id: I87e3813242dd3cd67138eae9efa96693fc598af0
This commit is contained in:
James E. Blair 2017-07-26 16:09:34 -07:00
parent 6cfb9b6826
commit d134c6ddf0
6 changed files with 221 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
doc/source/admin/drivers/gerrit.rst
View File

@ -146,8 +146,8 @@ The supported pipeline trigger options are:
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.
<gerrit-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
@ -170,3 +170,102 @@ with a value. For example, ``verified: 1`` becomes ``gerrit review
A :ref:`connection<connections>` that uses the gerrit driver must be
supplied to the trigger.
Requirements Configuration
--------------------------
As described in :ref:`pipeline.require <pipeline-require>` and
:ref:`pipeline.reject <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 congfiguration such as the
following::
pipeline:
require:
my-gerrit:
approval:
- 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.
.. zuul:configobject:: pipeline.require.<source>
The dictionary passed to the Gerrit pipeline `require` attribute
supports the following attributes:
.. _gerrit-pipeline-require-approval:
.. zuul:attr:: approval
This 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 takes several sub-parameters, all of
which are optional and are combined together so that there must
be an approval matching all specified requirements.
.. zuul:attr:: username
If present, an approval from this username is required. It is
treated as a regular expression.
.. zuul:attr:: email
If present, an approval with this email address is required. It is
treated as a regular expression.
.. zuul:attr:: older-than
If present, the approval must be older than this amount of time
to match. Provide a time interval as a number with a suffix of
"w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s"
(seconds). Example ``48h`` or ``2d``.
.. zuul:attr:: newer-than
If present, the approval must be newer than this amount
of time to match. Same format as "older-than".
Any other field is interpreted as a review category and value
pair. For example ``Verified: 1`` would require that the
approval be for a +1 vote in the "Verified" column. The value
may either be a single value or a list: ``Verified: [1, 2]``
would match either a +1 or +2 vote.
.. zuul:attr:: open
A boolean value (``true`` or ``false``) that indicates whether
the change must be open or closed in order to be enqueued.
.. zuul:attr:: current-patchset
A boolean value (``true`` or ``false``) that indicates whether the
change must be the current patchset in order to be enqueued.
.. zuul:attr:: status
A string value that corresponds with the status of the change
reported by the trigger.
.. zuul:configobject:: pipeline.reject.<source>
The `reject` attribute is the mirror of the `require` attribute. It
also accepts a dictionary under the connection name. This
dictionary supports the following attributes:
.. zuul:attr:: approval
This takes a list of approvals. If an approval matches the
provided criteria the change can not be entered into the
pipeline. It follows the same syntax as the :ref:`approval
pipeline requirement above <gerrit-pipeline-require-approval>`.
Example to reject a change with any negative vote::
reject:
my-gerrit:
approval:
- code-review: [-1, -2]

108
doc/source/admin/drivers/github.rst
View File

@ -194,3 +194,111 @@ supplied to the reporter. It has the following options:
Request based events. ``unlabel: 'test failed'``
.. _Github App: https://developer.github.com/apps/
Requirements Configuration
--------------------------
As described in :ref:`pipeline.require <pipeline-require>` and
:ref:`pipeline.reject <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 GitHub
source named *my-github*, create a congfiguration such as the
following::
pipeline:
require:
my-github:
review:
- type: approval
This indicates that changes originating from the GitHub connection
named *my-github* must have an approved code review in order to be
enqueued into the pipeline.
.. zuul:configobject:: pipeline.require.<source>
The dictionary passed to the GitHub pipeline `require` attribute
supports the following attributes:
.. _github-pipeline-require-review:
.. zuul:attr:: review
This requires that a certain kind of code review be present for
the pull request (it could be added by the event in question).
It takes several sub-parameters, all of which are optional and
are combined together so that there must be a code review
matching all specified requirements.
.. zuul:attr:: username
If present, a code review from this username is required. It
is treated as a regular expression.
.. zuul:attr:: email
If present, a code review with this email address is
required. It is treated as a regular expression.
.. zuul:attr:: older-than
If present, the code review must be older than this amount of
time to match. Provide a time interval as a number with a
suffix of "w" (weeks), "d" (days), "h" (hours), "m"
(minutes), "s" (seconds). Example ``48h`` or ``2d``.
.. zuul:attr:: newer-than
If present, the code review must be newer than this amount of
time to match. Same format as "older-than".
.. zuul:attr:: type
If present, the code review must match this type (or types).
.. TODO: what types are valid?
.. zuul:attr:: permission
If present, the author of the code review must have this
permission (or permissions). The available values are
``read``, ``write``, and ``admin``.
.. zuul:attr:: open
A boolean value (``true`` or ``false``) that indicates whether
the change must be open or closed in order to be enqueued.
.. zuul:attr:: current-patchset
A boolean value (``true`` or ``false``) that indicates whether
the item must be associated with the latest commit in the pull
request in order to be enqueued.
.. TODO: this could probably be expanded upon -- under what
circumstances might this happen with github
.. zuul:attr:: status
A string value that corresponds with the status of the pull
request. The syntax is ``user:status:value``.
.. zuul:attr:: label
A string value indicating that the pull request must have the
indicated label (or labels).
.. zuul:configobject:: pipeline.reject.<source>
The `reject` attribute is the mirror of the `require` attribute. It
also accepts a dictionary under the connection name. This
dictionary supports the following attributes:
.. zuul:attr:: review
This takes a list of code reviews. If a code review matches the
provided criteria the pull request can not be entered into the
pipeline. It follows the same syntax as the :ref:`review
pipeline requirement above <github-pipeline-require-review>`.

13
doc/source/admin/drivers/zuul.rst
View File

@ -25,16 +25,3 @@ can simply be used by listing **zuul** as the trigger.
**pipeline**
Only available for ``parent-change-enqueued`` events. This is the
name of the pipeline in which the parent change was enqueued.
**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.

79
doc/source/user/config.rst
View File

@ -234,68 +234,22 @@ success, the pipeline reports back to Gerrit with a *Verified* vote of
of the connection will dictate which options are available. See
:ref:`drivers`.
.. _pipeline-require:
.. zuul:attr:: require
If this section is present, it established pre-requisites for
If this section is present, it establishes pre-requisites for
any kind of item entering the Pipeline. Regardless of how the
item is to be enqueued (via any trigger or automatic dependency
resolution), the conditions specified here must be met or the
item will not be enqueued.
item will not be enqueued. These requirements may vary
depending on the source of the item being enqueued.
.. _pipeline-require-approval:
Requirements are loaded from their connection name. The driver
type of the connection will dictate which options are available.
See :ref:`drivers`.
.. zuul:attr:: approval
This 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 takes several
sub-parameters, all of which are optional and are combined
together so that there must be an approval matching all
specified requirements.
.. zuul:attr:: username
If present, an approval from this username is required. It is
treated as a regular expression.
.. zuul:attr:: email
If present, an approval with this email address is required. It
is treated as a regular expression.
.. zuul:attr:: older-than
If present, the approval must be older than this amount
of time to match. Provide a time interval as a number
with a suffix of "w" (weeks), "d" (days), "h" (hours),
"m" (minutes), "s" (seconds). Example ``48h`` or ``2d``.
.. zuul:attr:: newer-than
If present, the approval must be newer than this amount
of time to match. Same format as "older-than".
Any other field is interpreted as a review category and
value pair. For example ``Verified: 1`` would require that
the approval be for a +1 vote in the "Verified" column. The
value may either be a single value or a list: ``Verified:
[1, 2]`` would match either a +1 or +2 vote.
.. zuul:attr:: open
A boolean value (``true`` or ``false``) that indicates whether
the change must be open or closed in order to be enqueued.
.. zuul:attr:: current-patchset
A boolean value (``true`` or ``false``) that indicates whether
the change must be the current patchset in order to be
enqueued.
.. zuul:attr:: status
A string value that corresponds with the status of the change
reported by the trigger.
.. _pipeline-reject:
.. zuul:attr:: reject
@ -303,18 +257,9 @@ success, the pipeline reports back to Gerrit with a *Verified* vote of
can block an item from being enqueued. It can be considered a
negative version of **require**.
.. zuul:attr:: approval
This takes a list of approvals. If an approval matches the
provided criteria the change can not be entered into the
pipeline. It follows the same syntax as the :ref:`"require
approval" pipeline above <pipeline-require-approval>`.
Example to reject a change with any negative vote::
reject:
approval:
- code-review: [-1, -2]
Requirements are loaded from their connection name. The driver
type of the connection will dictate which options are available.
See :ref:`drivers`.
.. zuul:attr:: dequeue-on-new-patchset

15
zuul/configloader.py
View File

@ -762,19 +762,6 @@ class PipelineParser(object):
precedence = vs.Any('normal', 'low', 'high')
approval = vs.Schema({'username': str,
'email': str,
'older-than': str,
'newer-than': str,
}, extra=vs.ALLOW_EXTRA)
require = {'approval': to_list(approval),
'open': bool,
'current-patchset': bool,
'status': to_list(str)}
reject = {'approval': to_list(approval)}
window = vs.All(int, vs.Range(min=0))
window_floor = vs.All(int, vs.Range(min=1))
window_type = vs.Any('linear', 'exponential')
@ -784,8 +771,6 @@ class PipelineParser(object):
vs.Required('manager'): manager,
'precedence': precedence,
'description': str,
'require': require,
'reject': reject,
'success-message': str,
'failure-message': str,
'merge-failure-message': str,

8
zuul/driver/zuul/zuultrigger.py
View File

@ -43,19 +43,11 @@ class ZuulTrigger(BaseTrigger):
def getSchema():
approval = v.Schema({'username': str,
'email': str,
'older-than': str,
'newer-than': str,
}, extra=v.ALLOW_EXTRA)
zuul_trigger = {
v.Required('event'):
scalar_or_list(v.Any('parent-change-enqueued',
'project-change-merged')),
'pipeline': scalar_or_list(str),
'require-approval': scalar_or_list(approval),
'reject-approval': scalar_or_list(approval),
}
return zuul_trigger