Check out implicit branch in timer jobs
So that we may re-use the same jobs for pre and post merge tests,
enqueue an item for every branch of every timer-triggered project
and checkout that branch before running the job. This means that
rather than having a job for gate plus a job for each stable branch,
we hav just have a single job which runs with different content.
The old method is still supported using override branches.
This updates the model to include Change, Branch, Tag, and Ref
objects which can be used as the value of Item.change. Branch,
Tag, and Ref are all very similar, but the distinction may help
us ensure that we're encoding the right information about the items
we are enqueing. This is important for branch matching in pipelines
and is also used to provide job variables.
Change-Id: I5c41d2dcbbbd1c17d68074cd7480e6ab83f884ea
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index c2c376e..db13460 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -107,8 +107,163 @@
~~~~~~~~~~~~~~
Zuul supplies not only the variables specified by the job definition
-to Ansible, but also some variables from the executor itself. They
-are:
+to Ansible, but also some variables from the Zuul itself.
+
+When a pipeline is triggered an action, it enqueues items which may
+vary based on the pipeline's configuration. For example, when a new
+change is created, that change may be enqueued into the pipeline,
+while a tag may be enqueued into the pipeline when it is pushed.
+
+Information about these items is available to jobs. All of the items
+enqueued in a pipeline are git references, and therefore share some
+attributes in common. But other attributes may vary based on the type
+of item.
+
+All items provide the following information as Ansible variables:
+
+**zuul.uuid**
+ The UUID of the build. A build is a single execution of a job.
+ When an item is enqueued into a pipeline, this usually results in
+ one build of each job configured for that item's project. However,
+ items may be re-enqueued in which case another build may run. In
+ dependent pipelines, the same job may run multiple times for the
+ same item as circumstances change ahead in the queue. Each time a
+ job is run, for whatever reason, it is acompanied with a new
+ unique id.
+
+.. TODO: rename build
+
+**zuul.buildset**
+ The build set UUID. When Zuul runs jobs for an item, the collection
+ of those jobs is known as a buildset. If the configuration of items
+ ahead in a dependent pipeline changes, Zuul creates a new buildset
+ and restarts all of the jobs.
+
+**zuul.ref**
+ The git ref of the item. This will be the full path (e.g.,
+ 'refs/heads/master' or 'refs/changes/...').
+
+**zuul.pipeline**
+ The name of the pipeline in which the job is being run.
+
+**zuul.job**
+ The name of the job being run.
+
+**zuul.project**
+ The item's project. This is a data structure with the following
+ fields:
+
+**zuul.project.name**
+ The name of the project, excluding hostname. E.g., `org/project`.
+
+**zuul.project.canonical_hostname**
+ The canonical hostname where the project lives. E.g.,
+ `git.example.com`.
+
+**zuul.project.canonical_name**
+ The full canonical name of the project including hostname. E.g.,
+ `git.example.com/org/project`.
+
+**zuul.tenant**
+ The name of the current Zuul tenant.
+
+**zuul.tags**
+ A list of tags associated with the job. Not to be confused with git
+ tags, these are simply free-form text fields that can be used by the
+ job for reporting or classification purposes.
+
+.. TODO: rename jobtags
+
+**zuul.items**
+ A data structure representing the items being tested with this
+ change.
+
+.. TODO: implement and document items
+
+
+Change Items
+++++++++++++
+
+A change to the repository. Most often, this will be a git reference
+which has not yet been merged into the repository (e.g., a gerrit
+change or a GitHub pull request). The following additional variables
+are available:
+
+**zuul.branch**
+ The target branch of the change (without the `refs/heads/` prefix).
+
+**zuul.change**
+ The identifier for the change.
+
+**zuul.patchset**
+ The patchset identifier for the change. If a change is revised,
+ this will have a different value.
+
+Branch Items
+++++++++++++
+
+This represents a branch tip. This item may have been enqueued
+because the branch was updated (via a change having merged, or a
+direct push). Or it may have been enqueued by a timer for the purpose
+of verifying the current condition of the branch. The following
+additional variables are available:
+
+**zuul.branch**
+ The name of the item's branch (without the `refs/heads/` prefix).
+
+**zuul.oldrev**
+ If the item was enqueued as the result of a change merging or being
+ pushed to the branch, the git sha of the old revision will be
+ included here. Otherwise, this value will not be present.
+
+**zuul.newrev**
+ If the item was enqueued as the result of a change merging or being
+ pushed to the branch, the git sha of the new revision will be
+ included here. Otherwise, this value will not be present.
+
+Tag Items
++++++++++
+
+This represents a git tag. The item may have been enqueued because a
+tag was created or deleted. The following additional variables are
+available:
+
+**zuul.tag**
+ The name of the item's tag (without the `refs/tags/` prefix).
+
+**zuul.oldrev**
+ If the item was enqueued as the result of a tag being created or
+ deleted the git sha of the old revision will be included here.
+ Otherwise, this value will not be present.
+
+**zuul.newrev**
+ If the item was enqueued as the result of a tag being created or
+ deleted the git sha of the new revision will be included here.
+ Otherwise, this value will not be present.
+
+Ref Items
++++++++++
+
+This represents a git reference that is neither a change, branch, or
+tag. Note that all items include a `ref` attribute which may be used
+to identify the ref. The following additional variables are
+available:
+
+**zuul.oldrev**
+ If the item was enqueued as the result of a ref being created,
+ deleted, or changed the git sha of the old revision will be included
+ here. Otherwise, this value will not be present.
+
+**zuul.newrev**
+ If the item was enqueued as the result of a ref being created,
+ deleted, or changed the git sha of the new revision will be included
+ here. Otherwise, this value will not be present.
+
+Working Directory
++++++++++++++++++
+
+Additionally, some information about the working directory and the
+executor running the job is available:
**zuul.executor.hostname**
The hostname of the executor.