Use zuul config sphinx directives for pipeline
This updates the entire pipeline config to use the new directives.
The content is generally not changed.
Change-Id: I213cb9447f2333ef6c186e0ff1ada782bcf27249
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 5584762..2084c9c 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -124,292 +124,333 @@
.. zuul:configobject:: pipeline
-The attributes available on a pipeline are as follows (all are
-optional unless otherwise specified):
+ The attributes available on a pipeline are as follows (all are
+ optional unless otherwise specified):
- .. zuul:attr:: name
- :required:
+ .. zuul:attr:: name
+ :required:
- This is used later in the project definition to indicate what jobs
- should be run for events in the pipeline.
+ This is used later in the project definition to indicate what jobs
+ should be run for events in the pipeline.
- .. zuul:attr:: manager
- :required:
+ .. zuul:attr:: manager
+ :required:
- There are currently two schemes for managing pipelines:
+ There are currently two schemes for managing pipelines:
- .. _independent_pipeline_manager:
+ .. _independent_pipeline_manager:
- .. zuul:value:: independent
+ .. zuul:value:: independent
- Every event in this pipeline should be treated as independent of
- other events in the pipeline. This is appropriate when the order
- of events in the pipeline doesn't matter because the results of
- the actions this pipeline performs can not affect other events in
- the pipeline. For example, when a change is first uploaded for
- review, you may want to run tests on that change to provide early
- feedback to reviewers. At the end of the tests, the change is
- not going to be merged, so it is safe to run these tests in
- parallel without regard to any other changes in the pipeline.
- They are independent.
+ Every event in this pipeline should be treated as independent
+ of other events in the pipeline. This is appropriate when
+ the order of events in the pipeline doesn't matter because
+ the results of the actions this pipeline performs can not
+ affect other events in the pipeline. For example, when a
+ change is first uploaded for review, you may want to run
+ tests on that change to provide early feedback to reviewers.
+ At the end of the tests, the change is not going to be
+ merged, so it is safe to run these tests in parallel without
+ regard to any other changes in the pipeline. They are
+ independent.
- Another type of pipeline that is independent is a post-merge
- pipeline. In that case, the changes have already merged, so the
- results can not affect any other events in the pipeline.
+ Another type of pipeline that is independent is a post-merge
+ pipeline. In that case, the changes have already merged, so
+ the results can not affect any other events in the pipeline.
- .. _dependent_pipeline_manager:
+ .. _dependent_pipeline_manager:
- .. zuul:value:: dependent
+ .. zuul:value:: dependent
- The dependent pipeline manager is designed for gating. It
- ensures that every change is tested exactly as it is going to be
- merged into the repository. An ideal gating system would test
- one change at a time, applied to the tip of the repository, and
- only if that change passed tests would it be merged. Then the
- next change in line would be tested the same way. In order to
- achieve parallel testing of changes, the dependent pipeline
- manager performs speculative execution on changes. It orders
- changes based on their entry into the pipeline. It begins
- testing all changes in parallel, assuming that each change ahead
- in the pipeline will pass its tests. If they all succeed, all
- the changes can be tested and merged in parallel. If a change
- near the front of the pipeline fails its tests, each change
- behind it ignores whatever tests have been completed and are
- tested again without the change in front. This way gate tests
- may run in parallel but still be tested correctly, exactly as
- they will appear in the repository when merged.
+ The dependent pipeline manager is designed for gating. It
+ ensures that every change is tested exactly as it is going to
+ be merged into the repository. An ideal gating system would
+ test one change at a time, applied to the tip of the
+ repository, and only if that change passed tests would it be
+ merged. Then the next change in line would be tested the
+ same way. In order to achieve parallel testing of changes,
+ the dependent pipeline manager performs speculative execution
+ on changes. It orders changes based on their entry into the
+ pipeline. It begins testing all changes in parallel,
+ assuming that each change ahead in the pipeline will pass its
+ tests. If they all succeed, all the changes can be tested
+ and merged in parallel. If a change near the front of the
+ pipeline fails its tests, each change behind it ignores
+ whatever tests have been completed and are tested again
+ without the change in front. This way gate tests may run in
+ parallel but still be tested correctly, exactly as they will
+ appear in the repository when merged.
- For more detail on the theory and operation of Zuul's dependent
- pipeline manager, see: :doc:`gating`.
+ For more detail on the theory and operation of Zuul's
+ dependent pipeline manager, see: :doc:`gating`.
-**allow-secrets**
- This is a boolean which can be used to prevent jobs which require
- secrets from running in this pipeline. Some pipelines run on
- proposed changes and therefore execute code which has not yet been
- reviewed. In such a case, allowing a job to use a secret could
- result in that secret being exposed. The default is False, meaning
- that in order to run jobs with secrets, this must be explicitly
- enabled on each Pipeline where that is safe.
+ .. zuul:attr:: allow-secrets
- For more information, see :ref:`secret`.
+ This is a boolean which can be used to prevent jobs which
+ require secrets from running in this pipeline. Some pipelines
+ run on proposed changes and therefore execute code which has not
+ yet been reviewed. In such a case, allowing a job to use a
+ secret could result in that secret being exposed. The default
+ is False, meaning that in order to run jobs with secrets, this
+ must be explicitly enabled on each Pipeline where that is safe.
-**description**
- This field may be used to provide a textual description of the
- pipeline. It may appear in the status page or in documentation.
+ For more information, see :ref:`secret`.
-**success-message**
- The introductory text in reports when all the voting jobs are
- successful. Defaults to "Build successful."
+ .. zuul:attr:: description
-**failure-message**
- The introductory text in reports when at least one voting job fails.
- Defaults to "Build failed."
+ This field may be used to provide a textual description of the
+ pipeline. It may appear in the status page or in documentation.
-**merge-failure-message**
- The introductory text in the message reported when a change fails to
- merge with the current state of the repository. Defaults to "Merge
- failed."
+ .. zuul:attr:: success-message
-**footer-message**
- Supplies additional information after test results. Useful for
- adding information about the CI system such as debugging and contact
- details.
+ The introductory text in reports when all the voting jobs are
+ successful. Defaults to "Build successful."
-**trigger**
- At least one trigger source must be supplied for each pipeline.
- Triggers are not exclusive -- matching events may be placed in
- multiple pipelines, and they will behave independently in each of
- the pipelines they match.
+ .. zuul:attr:: failure-message
- Triggers are loaded from their connection name. The driver type of
- the connection will dictate which options are available.
- See :ref:`drivers`.
+ The introductory text in reports when at least one voting job
+ fails. Defaults to "Build failed."
-**require**
- If this section is present, it established 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.
+ .. zuul:attr:: merge-failure-message
-.. _pipeline-require-approval:
+ The introductory text in the message reported when a change
+ fails to merge with the current state of the repository.
+ Defaults to "Merge failed."
- **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:: footer-message
- *username*
- If present, an approval from this username is required. It is
- treated as a regular expression.
+ Supplies additional information after test results. Useful for
+ adding information about the CI system such as debugging and
+ contact details.
- *email*
- If present, an approval with this email address is required. It
- is treated as a regular expression.
+ .. zuul:attr:: trigger
- *email-filter* (deprecated)
- A deprecated alternate spelling of *email*. Only one of *email* or
- *email_filter* should be used.
+ At least one trigger source must be supplied for each pipeline.
+ Triggers are not exclusive -- matching events may be placed in
+ multiple pipelines, and they will behave independently in each
+ of the pipelines they match.
- *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``.
+ Triggers are loaded from their connection name. The driver type
+ of the connection will dictate which options are available. See
+ :ref:`drivers`.
- *newer-than*
- If present, the approval must be newer than this amount of time
- to match. Same format as "older-than".
+ .. zuul:attr:: require
- 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.
+ If this section is present, it established 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.
- **open**
- A boolean value (``true`` or ``false``) that indicates whether the change
- must be open or closed in order to be enqueued.
+ .. _pipeline-require-approval:
- **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:: approval
- **status**
- A string value that corresponds with the status of the change
- reported by the trigger.
+ 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.
-**reject**
- If this section is present, it establishes pre-requisites that can
- block an item from being enqueued. It can be considered a negative
- version of **require**.
+ .. zuul:attr:: username
- **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>`.
+ If present, an approval from this username is required. It is
+ treated as a regular expression.
- Example to reject a change with any negative vote::
+ .. zuul:attr:: email
- reject:
- approval:
- - Code-Review: [-1, -2]
+ If present, an approval with this email address is required. It
+ is treated as a regular expression.
-**dequeue-on-new-patchset**
- Normally, if a new patchset is uploaded to a change that is in a
- pipeline, the existing entry in the pipeline will be removed (with
- jobs canceled and any dependent changes that can no longer merge as
- well. To suppress this behavior (and allow jobs to continue
- running), set this to ``false``. Default: ``true``.
+ .. zuul:attr:: email-filter (deprecated)
-**ignore-dependencies**
- In any kind of pipeline (dependent or independent), Zuul will
- attempt to enqueue all dependencies ahead of the current change so
- that they are tested together (independent pipelines report the
- results of each change regardless of the results of changes ahead).
- To ignore dependencies completely in an independent pipeline, set
- this to ``true``. This option is ignored by dependent pipelines.
- The default is: ``false``.
+ A deprecated alternate spelling of *email*. Only one of
+ *email* or *email_filter* should be used.
-**precedence**
- Indicates how the build scheduler should prioritize jobs for
- different pipelines. Each pipeline may have one precedence, jobs
- for pipelines with a higher precedence will be run before ones with
- lower. The value should be one of ``high``, ``normal``, or ``low``.
- Default: ``normal``.
+ .. zuul:attr:: older-than
-The following options configure *reporters*. Reporters are
-complementary to triggers; where a trigger is an event on a connection
-which causes Zuul to enqueue an item, a reporter is the action
-performed on a connection when an item is dequeued after its jobs
-complete. The actual syntax for a reporter is defined by the driver
-which implements it. See :ref:`drivers` for more information.
+ 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``.
-**success**
- 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 report at all. If
- the section is present, the listed reporters will be asked to report
- on the jobs. The reporters are listed by their connection name. The
- options available depend on the driver for the supplied connection.
+ .. zuul:attr:: newer-than
-**failure**
- These reporters describe what Zuul should do if at least one job
- fails.
+ If present, the approval must be newer than this amount
+ of time to match. Same format as "older-than".
-**merge-failure**
- These reporters describe what Zuul should do if it is unable to
- merge in the patchset. If no merge-failure reporters are listed then
- the ``failure`` reporters will be used to notify of unsuccessful
- merges.
+ 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.
-**start**
- These reporters describe what Zuul should do when a change is added
- to the pipeline. This can be used, for example, to reset a
- previously reported result.
+ .. zuul:attr:: open
-**disabled**
- These reporters describe what Zuul should do when a pipeline is
- disabled. See ``disable-after-consecutive-failures``.
+ A boolean value (``true`` or ``false``) that indicates whether
+ the change must be open or closed in order to be enqueued.
-The following options can be used to alter Zuul's behavior to mitigate
-situations in which jobs are failing frequently (perhaps due to a
-problem with an external dependency, or unusually high
-non-deterministic test failures).
+ .. zuul:attr:: current-patchset
-**disable-after-consecutive-failures**
- If set, a pipeline can enter a ''disabled'' state if too many changes
- in a row fail. When this value is exceeded the pipeline will stop
- reporting to any of the ``success``, ``failure`` or ``merge-failure``
- reporters and instead only report to the ``disabled`` reporters.
- (No ``start`` reports are made when a pipeline is disabled).
+ A boolean value (``true`` or ``false``) that indicates whether
+ the change must be the current patchset in order to be
+ enqueued.
-**window**
- Dependent pipeline managers only. Zuul can rate limit dependent
- pipelines in a manner similar to TCP flow control. Jobs are only
- started for items in the queue if they are within the actionable
- window for the pipeline. The initial length of this window is
- configurable with this value. The value given should be a positive
- integer value. A value of ``0`` disables rate limiting on the
- DependentPipelineManager. Default: ``20``.
+ .. zuul:attr:: status
-**window-floor**
- Dependent pipeline managers only. This is the minimum value for the
- window described above. Should be a positive non zero integer value.
- Default: ``3``.
+ A string value that corresponds with the status of the change
+ reported by the trigger.
-**window-increase-type**
- Dependent pipeline managers only. This value describes how the window
- should grow when changes are successfully merged by zuul. A value of
- ``linear`` indicates that ``window-increase-factor`` should be added
- to the previous window value. A value of ``exponential`` indicates
- that ``window-increase-factor`` should be multiplied against the
- previous window value and the result will become the window size.
- Default: ``linear``.
+ .. zuul:attr:: reject
-**window-increase-factor**
- Dependent pipeline managers only. The value to be added or multiplied
- against the previous window value to determine the new window after
- successful change merges.
- Default: ``1``.
+ If this section is present, it establishes pre-requisites that
+ can block an item from being enqueued. It can be considered a
+ negative version of **require**.
-**window-decrease-type**
- Dependent pipeline managers only. This value describes how the window
- should shrink when changes are not able to be merged by Zuul. A value
- of ``linear`` indicates that ``window-decrease-factor`` should be
- subtracted from the previous window value. A value of ``exponential``
- indicates that ``window-decrease-factor`` should be divided against
- the previous window value and the result will become the window size.
- Default: ``exponential``.
+ .. zuul:attr:: approval
-**window-decrease-factor**
- Dependent pipline managers only. The value to be subtracted or divided
- against the previous window value to determine the new window after
- unsuccessful change merges.
- Default: ``2``.
+ 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]
+
+ .. zuul:attr:: dequeue-on-new-patchset
+
+ Normally, if a new patchset is uploaded to a change that is in a
+ pipeline, the existing entry in the pipeline will be removed
+ (with jobs canceled and any dependent changes that can no longer
+ merge as well. To suppress this behavior (and allow jobs to
+ continue running), set this to ``false``. Default: ``true``.
+
+ .. zuul:attr:: ignore-dependencies
+
+ In any kind of pipeline (dependent or independent), Zuul will
+ attempt to enqueue all dependencies ahead of the current change
+ so that they are tested together (independent pipelines report
+ the results of each change regardless of the results of changes
+ ahead). To ignore dependencies completely in an independent
+ pipeline, set this to ``true``. This option is ignored by
+ dependent pipelines. The default is: ``false``.
+
+ .. zuul:attr:: precedence
+
+ Indicates how the build scheduler should prioritize jobs for
+ different pipelines. Each pipeline may have one precedence,
+ jobs for pipelines with a higher precedence will be run before
+ ones with lower. The value should be one of ``high``,
+ ``normal``, or ``low``. Default: ``normal``.
+
+ The following options configure *reporters*. Reporters are
+ complementary to triggers; where a trigger is an event on a
+ connection which causes Zuul to enqueue an item, a reporter is the
+ action performed on a connection when an item is dequeued after its
+ jobs complete. The actual syntax for a reporter is defined by the
+ driver which implements it. See :ref:`drivers` for more
+ information.
+
+ .. zuul:attr:: success
+
+ 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 report at
+ all. If the section is present, the listed reporters will be
+ asked to report on the jobs. The reporters are listed by their
+ connection name. The options available depend on the driver for
+ the supplied connection.
+
+ .. zuul:attr:: failure
+
+ These reporters describe what Zuul should do if at least one job
+ fails.
+
+ .. zuul:attr:: merge-failure
+
+ These reporters describe what Zuul should do if it is unable to
+ merge in the patchset. If no merge-failure reporters are listed
+ then the ``failure`` reporters will be used to notify of
+ unsuccessful merges.
+
+ .. zuul:attr:: start
+
+ These reporters describe what Zuul should do when a change is
+ added to the pipeline. This can be used, for example, to reset
+ a previously reported result.
+
+ .. zuul:attr:: disabled
+
+ These reporters describe what Zuul should do when a pipeline is
+ disabled. See ``disable-after-consecutive-failures``.
+
+ The following options can be used to alter Zuul's behavior to
+ mitigate situations in which jobs are failing frequently (perhaps
+ due to a problem with an external dependency, or unusually high
+ non-deterministic test failures).
+
+ .. zuul:attr:: disable-after-consecutive-failures
+
+ If set, a pipeline can enter a ''disabled'' state if too many
+ changes in a row fail. When this value is exceeded the pipeline
+ will stop reporting to any of the ``success``, ``failure`` or
+ ``merge-failure`` reporters and instead only report to the
+ ``disabled`` reporters. (No ``start`` reports are made when a
+ pipeline is disabled).
+
+ .. zuul:attr:: window
+
+ Dependent pipeline managers only. Zuul can rate limit dependent
+ pipelines in a manner similar to TCP flow control. Jobs are
+ only started for items in the queue if they are within the
+ actionable window for the pipeline. The initial length of this
+ window is configurable with this value. The value given should
+ be a positive integer value. A value of ``0`` disables rate
+ limiting on the DependentPipelineManager. Default: ``20``.
+
+ .. zuul:attr:: window-floor
+
+ Dependent pipeline managers only. This is the minimum value for
+ the window described above. Should be a positive non zero
+ integer value. Default: ``3``.
+
+ .. zuul:attr:: window-increase-type
+
+ Dependent pipeline managers only. This value describes how the
+ window should grow when changes are successfully merged by
+ zuul. A value of ``linear`` indicates that
+ ``window-increase-factor`` should be added to the previous
+ window value. A value of ``exponential`` indicates that
+ ``window-increase-factor`` should be multiplied against the
+ previous window value and the result will become the window
+ size. Default: ``linear``.
+
+ .. zuul:attr:: window-increase-factor
+
+ Dependent pipeline managers only. The value to be added or
+ multiplied against the previous window value to determine the
+ new window after successful change merges. Default: ``1``.
+
+ .. zuul:attr:: window-decrease-type
+
+ Dependent pipeline managers only. This value describes how the
+ window should shrink when changes are not able to be merged by
+ Zuul. A value of ``linear`` indicates that
+ ``window-decrease-factor`` should be subtracted from the
+ previous window value. A value of ``exponential`` indicates that
+ ``window-decrease-factor`` should be divided against the
+ previous window value and the result will become the window
+ size. Default: ``exponential``.
+
+ .. zuul:attr:: window-decrease-factor
+
+ Dependent pipline managers only. The value to be subtracted or
+ divided against the previous window value to determine the new
+ window after unsuccessful change merges. Default: ``2``.
.. _job:
@@ -482,7 +523,7 @@
parent: base
nodes:
- name: test-node
- image: fedora
+ image: fedora
The following attributes are available on a job; all are optional
unless otherwise specified: