docs: reformat job section with zuul domain
Also start using some code-block sections.
Also fix some leftover :ref: and :zuul:value: entries from previous
patches.
Change-Id: I6350640f1f822c159e0eca088cc873f66f6bc46d
diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
index 48f8a33..454f8d0 100644
--- a/doc/source/admin/drivers/gerrit.rst
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -174,13 +174,12 @@
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 configuration such as the
-following::
+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::
pipeline:
require:
diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst
index 298e6b4..ed577a5 100644
--- a/doc/source/admin/drivers/github.rst
+++ b/doc/source/admin/drivers/github.rst
@@ -198,13 +198,12 @@
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::
+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 GitHub source named *my-github*, create a congfiguration such
+as the following::
pipeline:
require:
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 5ca8677..3eccbb5 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -105,20 +105,22 @@
Here is an example *check* pipeline, which runs whenever a new
patchset is created in Gerrit. If the associated jobs all report
success, the pipeline reports back to Gerrit with a *Verified* vote of
-+1, or if at least one of them fails, a -1::
++1, or if at least one of them fails, a -1:
- - pipeline:
- name: check
- manager: independent
- trigger:
- my_gerrit:
- - event: patchset-created
- success:
- my_gerrit:
- Verified: 1
- failure:
- my_gerrit
- Verified: -1
+.. code-block:: yaml
+
+ - pipeline:
+ name: check
+ manager: independent
+ trigger:
+ my_gerrit:
+ - event: patchset-created
+ success:
+ my_gerrit:
+ Verified: 1
+ failure:
+ my_gerrit
+ Verified: -1
.. TODO: See TODO for more annotated examples of common pipeline configurations.
@@ -138,7 +140,7 @@
There are currently two schemes for managing pipelines:
- .. zuul:value:: independent
+ .. value:: independent
Every event in this pipeline should be treated as independent
of other events in the pipeline. This is appropriate when
@@ -156,7 +158,7 @@
pipeline. In that case, the changes have already merged, so
the results can not affect any other events in the pipeline.
- .. zuul:value:: dependent
+ .. value:: dependent
The dependent pipeline manager is designed for gating. It
ensures that every change is tested exactly as it is going to
@@ -230,8 +232,6 @@
of the connection will dictate which options are available. See
:ref:`drivers`.
- .. _pipeline-require:
-
.. attr:: require
If this section is present, it establishes pre-requisites for
@@ -245,8 +245,6 @@
type of the connection will dictate which options are available.
See :ref:`drivers`.
- .. _pipeline-reject:
-
.. attr:: reject
If this section is present, it establishes pre-requisites that
@@ -447,365 +445,418 @@
Further inheritance would nest even deeper.
-Here is an example of two job definitions::
+Here is an example of two job definitions:
- - job:
- name: base
- pre-run: copy-git-repos
- post-run: copy-logs
+.. code-block:: yaml
- - job:
- name: run-tests
- parent: base
- nodes:
- - name: test-node
- image: fedora
+ - job:
+ name: base
+ pre-run: copy-git-repos
+ post-run: copy-logs
-The following attributes are available on a job; all are optional
-unless otherwise specified:
+ - job:
+ name: run-tests
+ parent: base
+ nodes:
+ - name: test-node
+ image: fedora
-**name** (required)
- The name of the job. By default, Zuul looks for a playbook with
- this name to use as the main playbook for the job. This name is
- also referenced later in a project pipeline configuration.
+.. attr:: job
-**parent**
- Specifies a job to inherit from. The parent job can be defined in
- this or any other project. Any attributes not specified on a job
- will be collected from its parent.
+ The following attributes are available on a job; all are optional
+ unless otherwise specified:
-**description**
- A textual description of the job. Not currently used directly by
- Zuul, but it is used by the zuul-sphinx extension to Sphinx to
- auto-document Zuul jobs (in which case it is interpreted as
- ReStructuredText.
+ .. attr:: name
+ :required:
-**success-message**
- Normally when a job succeeds, the string "SUCCESS" is reported as
- the result for the job. If set, this option may be used to supply a
- different string. Default: "SUCCESS".
+ The name of the job. By default, Zuul looks for a playbook with
+ this name to use as the main playbook for the job. This name is
+ also referenced later in a project pipeline configuration.
-**failure-message**
- Normally when a job fails, the string "FAILURE" is reported as
- the result for the job. If set, this option may be used to supply a
- different string. Default: "FAILURE".
+ .. attr:: parent
-**success-url**
- When a job succeeds, this URL is reported along with the result. If
- this value is not supplied, Zuul uses the content of the job
- :ref:`return value <return_values>` **zuul.log_url**. This is
- recommended as it allows the code which stores the URL to the job
- artifacts to report exactly where they were stored. To override
- this value, or if it is not set, supply an absolute URL in this
- field. If a relative URL is supplied in this field, and
- **zuul.log_url** is set, then the two will be combined to produce
- the URL used for the report. This can be used to specify that
- certain jobs should "deep link" into the stored job artifacts.
- Default: none.
+ Specifie s a job to inherit from. The parent job can be defined
+ in this or a ny other project. Any attributes not specified on
+ a job will be collected from its parent.
-**failure-url**
- When a job fails, this URL is reported along with the result.
- Otherwise behaves the same as **success-url**.
+ .. attr:: description
-**hold-following-changes**
- In a dependent pipeline, this option may be used to indicate that no
- jobs should start on any items which depend on the current item
- until this job has completed successfully. This may be used to
- conserve build resources, at the expense of inhibiting the
- parallelization which speeds the processing of items in a dependent
- pipeline. A boolean value, default: false.
+ A textual description of the job. Not currently used directly
+ by Zuul, but it is used by the zuul-sphinx extension to Sphinx
+ to auto-document Zuul jobs (in which case it is interpreted as
+ ReStructuredText.
-**voting**
- Indicates whether the result of this job should be used in
- determining the overall result of the item. A boolean value,
- default: true.
+ .. attr:: success-message
-**semaphore**
- The name of a :ref:`semaphore` which should be acquired and released
- when the job begins and ends. If the semaphore is at maximum
- capacity, then Zuul will wait until it can be acquired before
- starting the job. Default: none.
+ Normally when a job succeeds, the string "SUCCESS" is reported
+ as the result for the job. If set, this option may be used to
+ supply a different string. Default: "SUCCESS".
-**tags**
- Metadata about this job. Tags are units of information attached to
- the job; they do not affect Zuul's behavior, but they can be used
- within the job to characterize the job. For example, a job which
- tests a certain subsystem could be tagged with the name of that
- subsystem, and if the job's results are reported into a database,
- then the results of all jobs affecting that subsystem could be
- queried. This attribute is specified as a list of strings, and when
- inheriting jobs or applying variants, tags accumulate in a set, so
- the result is always a set of all the tags from all the jobs and
- variants used in constructing the frozen job, with no duplication.
- Default: none.
+ .. attr:: failure-message
-**branches**
- A regular expression (or list of regular expressions) which describe
- on what branches a job should run (or in the case of variants: to
- alter the behavior of a job for a certain branch).
+ Normally when a job fails, the string "FAILURE" is reported as
+ the result for the job. If set, this option may be used to
+ supply a different string. Default: "FAILURE".
- If there is no job definition for a given job which matches the
- branch of an item, then that job is not run for the item.
- Otherwise, all of the job variants which match that branch (and any
- other selection criteria) are used when freezing the job.
+ .. attr:: success-url
- This example illustrates a job called *run-tests* which uses a
- nodeset based on the current release of an operating system to
- perform its tests, except when testing changes to the stable/2.0
- branch, in which case it uses an older release::
+ When a job succeeds, this URL is reported along with the result.
+ If this value is not supplied, Zuul uses the content of the job
+ :ref:`return value <return_values>` **zuul.log_url**. This is
+ recommended as it allows the code which stores the URL to the
+ job artifacts to report exactly where they were stored. To
+ override this value, or if it is not set, supply an absolute URL
+ in this field. If a relative URL is supplied in this field, and
+ **zuul.log_url** is set, then the two will be combined to
+ produce the URL used for the report. This can be used to
+ specify that certain jobs should "deep link" into the stored job
+ artifacts. Default: none.
- - job:
- name: run-tests
- nodes: current-release
+ .. attr:: failure-url
- - job:
- name: run-tests
- branch: stable/2.0
- nodes: old-release
+ When a job fails, this URL is reported along with the result.
+ Otherwise behaves the same as **success-url**.
- In some cases, Zuul uses an implied value for the branch specifier
- if none is supplied:
+ .. attr:: hold-following-changes
- * For a job definition in a *config-project*, no implied branch
- specifier is used. If no branch specifier appears, the job
- applies to all branches.
+ In a dependent pipeline, this option may be used to indicate
+ that no jobs should start on any items which depend on the
+ current item until this job has completed successfully. This
+ may be used to conserve build resources, at the expense of
+ inhibiting the parallelization which speeds the processing of
+ items in a dependent pipeline. A boolean value, default: false.
- * In the case of an *untrusted-project*, no implied branch specifier
- is applied to the reference definition of a job. That is to say,
- that if the first appearance of the job definition appears without
- a branch specifier, then it will apply to all branches. Note that
- when collecting its configuration, Zuul reads the `master` branch
- of a given project first, then other branches in alphabetical
- order.
+ .. attr:: voting
- * Any further job variants other than the reference definition in an
- *untrusted-project* will, if they do not have a branch specifier,
- will have an implied branch specifier for the current branch
- applied.
+ Indicates whether the result of this job should be used in
+ determining the overall result of the item. A boolean value,
+ default: true.
- This allows for the very simple and expected workflow where if a
- project defines a job on the master branch with no branch specifier,
- and then creates a new branch based on master, any changes to that
- job definition within the new branch only affect that branch.
+ .. attr:: semaphore
-**files**
- This attribute indicates that the job should only run on changes
- where the specified files are modified. This is a regular
- expression or list of regular expressions. Default: none.
+ The name of a :ref:`semaphore` which should be acquired and
+ released when the job begins and ends. If the semaphore is at
+ maximum capacity, then Zuul will wait until it can be acquired
+ before starting the job. Default: none.
-**irrelevant-files**
- This is a negative complement of `files`. It indicates that the job
- should run unless *all* of the files changed match this list. In
- other words, if the regular expression `docs/.*` is supplied, then
- this job will not run if the only files changed are in the docs
- directory. A regular expression or list of regular expressions.
- Default: none.
+ .. attr:: tags
-**auth**
- Authentication information to be made available to the job. This is
- a dictionary with two potential keys:
+ Metadata about this job. Tags are units of information attached
+ to the job; they do not affect Zuul's behavior, but they can be
+ used within the job to characterize the job. For example, a job
+ which tests a certain subsystem could be tagged with the name of
+ that subsystem, and if the job's results are reported into a
+ database, then the results of all jobs affecting that subsystem
+ could be queried. This attribute is specified as a list of
+ strings, and when inheriting jobs or applying variants, tags
+ accumulate in a set, so the result is always a set of all the
+ tags from all the jobs and variants used in constructing the
+ frozen job, with no duplication. Default: none.
- **inherit**
- A boolean indicating that the authentication information referenced
- by this job should be able to be inherited by child jobs. Normally
- when a job inherits from another job, the auth section is not
- included. This permits jobs to inherit the same basic structure and
- playbook, but ensures that secret information is unable to be
- exposed by a child job which may alter the job's behavior. If it is
- safe for the contents of the authentication section to be used by
- child jobs, set this to ``true``. Default: ``false``.
+ .. attr:: branches
- **secrets**
- A list of secrets which may be used by the job. A :ref:`secret` is
- a named collection of private information defined separately in the
- configuration. The secrets that appear here must be defined in the
- same project as this job definition.
+ A regular expression (or list of regular expressions) which
+ describe on what branches a job should run (or in the case of
+ variants: to alter the behavior of a job for a certain branch).
- In the future, other types of authentication information may be
- added.
+ If there is no job definition for a given job which matches the
+ branch of an item, then that job is not run for the item.
+ Otherwise, all of the job variants which match that branch (and
+ any other selection criteria) are used when freezing the job.
-**nodes**
- A list of nodes which should be supplied to the job. This parameter
- may be supplied either as a string, in which case it references a
- :ref:`nodeset` definition which appears elsewhere in the
- configuration, or a list, in which case it is interpreted in the
- same way as a Nodeset definition (in essence, it is an anonymous
- Node definition unique to this job). See the :ref:`nodeset`
- reference for the syntax to use in that case.
+ This example illustrates a job called *run-tests* which uses a
+ nodeset based on the current release of an operating system to
+ perform its tests, except when testing changes to the stable/2.0
+ branch, in which case it uses an older release:
- If a job has an empty or no node definition, it will still run and
- may be able to perform actions on the Zuul executor.
+ .. code-block:: yaml
-**override-branch**
- When Zuul runs jobs for a proposed change, it normally checks out
- the branch associated with that change on every project present in
- the job. If jobs are running on a ref (such as a branch tip or
- tag), then that ref is normally checked out. This attribute is used
- to override that behavior and indicate that this job should,
- regardless of the branch for the queue item, use the indicated
- branch instead. This can be used, for example, to run a previous
- version of the software (from a stable maintenance branch) under
- test even if the change being tested applies to a different branch
- (this is only likely to be useful if there is some cross-branch
- interaction with some component of the system being tested). See
- also the project-specific **override-branch** attribute under
- **required-projects** to apply this behavior to a subset of a job's
- projects.
+ - job:
+ name: run-tests
+ nodes: current-release
-**timeout**
- The time in minutes that the job should be allowed to run before it
- is automatically aborted and failure is reported. If no timeout is
- supplied, the job may run indefinitely. Supplying a timeout is
- highly recommended.
+ - job:
+ name: run-tests
+ branch: stable/2.0
+ nodes: old-release
-**attempts**
- When Zuul encounters an error running a job's pre-run playbook, Zuul
- will stop and restart the job. Errors during the main or
- post-run -playbook phase of a job are not affected by this parameter
- (they are reported immediately). This parameter controls the number
- of attempts to make before an error is reported. Default: 3.
+ In some cases, Zuul uses an implied value for the branch specifier
+ if none is supplied:
-**pre-run**
- The name of a playbook or list of playbooks without file extension
- to run before the main body of a job. The full path to the playbook
- in the repo where the job is defined is expected.
+ * For a job definition in a *config-project*, no implied branch
+ specifier is used. If no branch specifier appears, the job
+ applies to all branches.
- When a job inherits from a parent, the child's pre-run playbooks are
- run after the parent's. See :ref:`job` for more information.
+ * In the case of an *untrusted-project*, no implied branch specifier
+ is applied to the reference definition of a job. That is to say,
+ that if the first appearance of the job definition appears without
+ a branch specifier, then it will apply to all branches. Note that
+ when collecting its configuration, Zuul reads the `master` branch
+ of a given project first, then other branches in alphabetical
+ order.
-**post-run**
- The name of a playbook or list of playbooks without file extension
- to run after the main body of a job. The full path to the playbook
- in the repo where the job is defined is expected.
+ * Any further job variants other than the reference definition in an
+ *untrusted-project* will, if they do not have a branch specifier,
+ will have an implied branch specifier for the current branch
+ applied.
- When a job inherits from a parent, the child's post-run playbooks
- are run before the parent's. See :ref:`job` for more information.
+ This allows for the very simple and expected workflow where if a
+ project defines a job on the master branch with no branch specifier,
+ and then creates a new branch based on master, any changes to that
+ job definition within the new branch only affect that branch.
-**run**
- The name of the main playbook for this job. This parameter is
- not normally necessary, as it defaults to a playbook with the
- same name as the job inside of the `playbooks/` directory (e.g.,
- the `foo` job would default to `playbooks/foo`. However, if a
- playbook with a different name is needed, it can be specified
- here. The file extension is not required, but the full path
- within the repo is. When a child inherits from a parent, a
- playbook with the name of the child job is implicitly searched
- first, before falling back on the playbook used by the parent
- job (unless the child job specifies a ``run`` attribute, in which
- case that value is used). Example::
+ .. attr:: files
- run: playbooks/<name of the job>
+ This attribute indicates that the job should only run on changes
+ where the specified files are modified. This is a regular
+ expression or list of regular expressions. Default: none.
-**roles**
- A list of Ansible roles to prepare for the job. Because a job runs
- an Ansible playbook, any roles which are used by the job must be
- prepared and installed by Zuul before the job begins. This value is
- a list of dictionaries, each of which indicates one of two types of
- roles: a Galaxy role, which is simply a role that is installed from
- Ansible Galaxy, or a Zuul role, which is a role provided by a
- project managed by Zuul. Zuul roles are able to benefit from
- speculative merging and cross-project dependencies when used by
- playbooks in untrusted projects. Roles are added to the Ansible
- role path in the order they appear on the job -- roles earlier in
- the list will take precedence over those which follow.
+ .. attr:: irrelevant-files
- In the case of job inheritance or variance, the roles used for each
- of the playbooks run by the job will be only those which were
- defined along with that playbook. If a child job inherits from a
- parent which defines a pre and post playbook, then the pre and post
- playbooks it inherits from the parent job will run only with the
- roles that were defined on the parent. If the child adds its own
- pre and post playbooks, then any roles added by the child will be
- available to the child's playbooks. This is so that a job which
- inherits from a parent does not inadvertantly alter the behavior of
- the parent's playbooks by the addition of conflicting roles. Roles
- added by a child will appear before those it inherits from its
- parent.
+ This is a negative complement of `files`. It indicates that the
+ job should run unless *all* of the files changed match this
+ list. In other words, if the regular expression `docs/.*` is
+ supplied, then this job will not run if the only files changed
+ are in the docs directory. A regular expression or list of
+ regular expressions. Default: none.
- A project which supplies a role may be structured in one of two
- configurations: a bare role (in which the role exists at the root of
- the project), or a contained role (in which the role exists within
- the `roles/` directory of the project, perhaps along with other
- roles). In the case of a contained role, the `roles/` directory of
- the project is added to the role search path. In the case of a bare
- role, the project itself is added to the role search path. In case
- the name of the project is not the name under which the role should
- be installed (and therefore referenced from Ansible), the `name`
- attribute may be used to specify an alternate.
+ .. attr:: auth
- A job automatically has the project in which it is defined added to
- the roles path if that project appears to contain a role or `roles/`
- directory. By default, the project is added to the path under its
- own name, however, that may be changed by explicitly listing the
- project in the roles list in the usual way.
+ Authentication information to be made available to the job.
+ This is a dictionary with two potential keys:
- .. note:: galaxy roles are not yet implemented
+ .. attr:: inherit
- **galaxy**
- The name of the role in Ansible Galaxy. If this attribute is
- supplied, Zuul will search Ansible Galaxy for a role by this name
- and install it. Mutually exclusive with ``zuul``; either
- ``galaxy`` or ``zuul`` must be supplied.
+ A boolean indicating that the authentication information
+ referenced by this job should be able to be inherited by
+ child jobs. Normally when a job inherits from another job,
+ the auth section is not included. This permits jobs to
+ inherit the same basic structure and playbook, but ensures
+ that secret information is unable to be exposed by a child
+ job which may alter the job's behavior. If it is safe for
+ the contents of the authentication section to be used by
+ child jobs, set this to ``true``. Default: ``false``.
- **zuul**
- The name of a Zuul project which supplies the role. Mutually
- exclusive with ``galaxy``; either ``galaxy`` or ``zuul`` must be
- supplied.
+ .. attr:: secrets
- **name**
- The installation name of the role. In the case of a bare role,
- the role will be made available under this name. Ignored in the
- case of a contained role.
+ A list of secrets which may be used by the job. A
+ :ref:`secret` is a named collection of private information
+ defined separately in the configuration. The secrets that
+ appear here must be defined in the same project as this job
+ definition.
-**required-projects**
- A list of other projects which are used by this job. Any Zuul
- projects specified here will also be checked out by Zuul into the
- working directory for the job. Speculative merging and cross-repo
- dependencies will be honored.
+ In the future, other types of authentication information may
+ be added.
- The format for this attribute is either a list of strings or
- dictionaries. Strings are interpreted as project names,
- dictionaries may have the following attributes:
+ .. attr:: nodes
- **name**
- The name of the required project.
+ A list of nodes which should be supplied to the job. This
+ parameter may be supplied either as a string, in which case it
+ references a :ref:`nodeset` definition which appears elsewhere
+ in the configuration, or a list, in which case it is interpreted
+ in the same way as a Nodeset definition (in essence, it is an
+ anonymous Node definition unique to this job). See the
+ :ref:`nodeset` reference for the syntax to use in that case.
- **override-branch**
- When Zuul runs jobs for a proposed change, it normally checks out
- the branch associated with that change on every project present in
- the job. If jobs are running on a ref (such as a branch tip or
- tag), then that ref is normally checked out. This attribute is
- used to override that behavior and indicate that this job should,
- regardless of the branch for the queue item, use the indicated
- branch instead, for only this project. See also the
- **override-branch** attribute of jobs to apply the same behavior
- to all projects in a job.
+ If a job has an empty or no node definition, it will still run
+ and may be able to perform actions on the Zuul executor.
-**vars**
+ .. attr:: override-branch
-A dictionary of variables to supply to Ansible. When inheriting from
-a job (or creating a variant of a job) vars are merged with previous
-definitions. This means a variable definition with the same name will
-override a previously defined variable, but new variable names will be
-added to the set of defined variables.
+ When Zuul runs jobs for a proposed change, it normally checks
+ out the branch associated with that change on every project
+ present in the job. If jobs are running on a ref (such as a
+ branch tip or tag), then that ref is normally checked out. This
+ attribute is used to override that behavior and indicate that
+ this job should, regardless of the branch for the queue item,
+ use the indicated branch instead. This can be used, for
+ example, to run a previous version of the software (from a
+ stable maintenance branch) under test even if the change being
+ tested applies to a different branch (this is only likely to be
+ useful if there is some cross-branch interaction with some
+ component of the system being tested). See also the
+ project-specific **override-branch** attribute under
+ **required-projects** to apply this behavior to a subset of a
+ job's projects.
-**dependencies**
- A list of other jobs upon which this job depends. Zuul will not
- start executing this job until all of its dependencies have
- completed successfully, and if one or more of them fail, this job
- will not be run.
+ .. attr:: timeout
-**allowed-projects**
- A list of Zuul projects which may use this job. By default, a job
- may be used by any other project known to Zuul, however, some jobs
- use resources or perform actions which are not appropriate for other
- projects. In these cases, a list of projects which are allowed to
- use this job may be supplied. If this list is not empty, then it
- must be an exhaustive list of all projects permitted to use the job.
- The current project (where the job is defined) is not automatically
- included, so if it should be able to run this job, then it must be
- explicitly listed. Default: the empty list (all projects may use
- the job).
+ The time in minutes that the job should be allowed to run before
+ it is automatically aborted and failure is reported. If no
+ timeout is supplied, the job may run indefinitely. Supplying a
+ timeout is highly recommended.
+
+ .. attr:: attempts
+
+ When Zuul encounters an error running a job's pre-run playbook,
+ Zuul will stop and restart the job. Errors during the main or
+ post-run -playbook phase of a job are not affected by this
+ parameter (they are reported immediately). This parameter
+ controls the number of attempts to make before an error is
+ reported. Default: 3.
+
+ .. attr:: pre-run
+
+ The name of a playbook or list of playbooks without file
+ extension to run before the main body of a job. The full path
+ to the playbook in the repo where the job is defined is
+ expected.
+
+ When a job inherits from a parent, the child's pre-run playbooks
+ are run after the parent's. See :ref:`job` for more
+ information.
+
+ .. attr:: post-run
+
+ The name of a playbook or list of playbooks without file
+ extension to run after the main body of a job. The full path to
+ the playbook in the repo where the job is defined is expected.
+
+ When a job inherits from a parent, the child's post-run
+ playbooks are run before the parent's. See :ref:`job` for more
+ information.
+
+ .. attr:: run
+
+ The name of the main playbook for this job. This parameter is
+ not normally necessary, as it defaults to a playbook with the
+ same name as the job inside of the `playbooks/` directory (e.g.,
+ the `foo` job would default to `playbooks/foo`. However, if a
+ playbook with a different name is needed, it can be specified
+ here. The file extension is not required, but the full path
+ within the repo is. When a child inherits from a parent, a
+ playbook with the name of the child job is implicitly searched
+ first, before falling back on the playbook used by the parent
+ job (unless the child job specifies a ``run`` attribute, in
+ which case that value is used). Example:
+
+ .. code-block:: yaml
+
+ run: playbooks/<name of the job>
+
+ .. attr:: roles
+
+ A list of Ansible roles to prepare for the job. Because a job
+ runs an Ansible playbook, any roles which are used by the job
+ must be prepared and installed by Zuul before the job begins.
+ This value is a list of dictionaries, each of which indicates
+ one of two types of roles: a Galaxy role, which is simply a role
+ that is installed from Ansible Galaxy, or a Zuul role, which is
+ a role provided by a project managed by Zuul. Zuul roles are
+ able to benefit from speculative merging and cross-project
+ dependencies when used by playbooks in untrusted projects.
+ Roles are added to the Ansible role path in the order they
+ appear on the job -- roles earlier in the list will take
+ precedence over those which follow.
+
+ In the case of job inheritance or variance, the roles used for
+ each of the playbooks run by the job will be only those which
+ were defined along with that playbook. If a child job inherits
+ from a parent which defines a pre and post playbook, then the
+ pre and post playbooks it inherits from the parent job will run
+ only with the roles that were defined on the parent. If the
+ child adds its own pre and post playbooks, then any roles added
+ by the child will be available to the child's playbooks. This
+ is so that a job which inherits from a parent does not
+ inadvertantly alter the behavior of the parent's playbooks by
+ the addition of conflicting roles. Roles added by a child will
+ appear before those it inherits from its parent.
+
+ A project which supplies a role may be structured in one of two
+ configurations: a bare role (in which the role exists at the
+ root of the project), or a contained role (in which the role
+ exists within the `roles/` directory of the project, perhaps
+ along with other roles). In the case of a contained role, the
+ `roles/` directory of the project is added to the role search
+ path. In the case of a bare role, the project itself is added
+ to the role search path. In case the name of the project is not
+ the name under which the role should be installed (and therefore
+ referenced from Ansible), the `name` attribute may be used to
+ specify an alternate.
+
+ A job automatically has the project in which it is defined added
+ to the roles path if that project appears to contain a role or
+ `roles/` directory. By default, the project is added to the
+ path under its own name, however, that may be changed by
+ explicitly listing the project in the roles list in the usual
+ way.
+
+ .. note:: Galaxy roles are not yet implemented.
+
+ .. attr:: galaxy
+
+ The name of the role in Ansible Galaxy. If this attribute is
+ supplied, Zuul will search Ansible Galaxy for a role by this
+ name and install it. Mutually exclusive with ``zuul``;
+ either ``galaxy`` or ``zuul`` must be supplied.
+
+ .. attr:: zuul
+
+ The name of a Zuul project which supplies the role. Mutually
+ exclusive with ``galaxy``; either ``galaxy`` or ``zuul`` must
+ be supplied.
+
+ .. attr:: name
+
+ The installation name of the role. In the case of a bare
+ role, the role will be made available under this name.
+ Ignored in the case of a contained role.
+
+ .. attr:: required-projects
+
+ A list of other projects which are used by this job. Any Zuul
+ projects specified here will also be checked out by Zuul into
+ the working directory for the job. Speculative merging and
+ cross-repo dependencies will be honored.
+
+ The format for this attribute is either a list of strings or
+ dictionaries. Strings are interpreted as project names,
+ dictionaries, if used, may have the following attributes:
+
+ .. attr:: name
+ :required:
+
+ The name of the required project.
+
+ .. attr:: override-branch
+
+ When Zuul runs jobs for a proposed change, it normally checks
+ out the branch associated with that change on every project
+ present in the job. If jobs are running on a ref (such as a
+ branch tip or tag), then that ref is normally checked out.
+ This attribute is used to override that behavior and indicate
+ that this job should, regardless of the branch for the queue
+ item, use the indicated branch instead, for only this
+ project. See also the **override-branch** attribute of jobs
+ to apply the same behavior to all projects in a job.
+
+ .. attr:: vars
+
+ A dictionary of variables to supply to Ansible. When inheriting
+ from a job (or creating a variant of a job) vars are merged with
+ previous definitions. This means a variable definition with the
+ same name will override a previously defined variable, but new
+ variable names will be added to the set of defined variables.
+
+ .. attr:: dependencies
+
+ A list of other jobs upon which this job depends. Zuul will not
+ start executing this job until all of its dependencies have
+ completed successfully, and if one or more of them fail, this
+ job will not be run.
+
+ .. attr:: allowed-projects
+
+ A list of Zuul projects which may use this job. By default, a
+ job may be used by any other project known to Zuul, however,
+ some jobs use resources or perform actions which are not
+ appropriate for other projects. In these cases, a list of
+ projects which are allowed to use this job may be supplied. If
+ this list is not empty, then it must be an exhaustive list of
+ all projects permitted to use the job. The current project
+ (where the job is defined) is not automatically included, so if
+ it should be able to run this job, then it must be explicitly
+ listed. Default: the empty list (all projects may use the job).
.. _project: