Add documentation about serving Zuul refs.
Change-Id: I6cdd20e6238fafdca626eb2531a3a78c985bb680
Reviewed-on: https://review.openstack.org/13974
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Approved: James E. Blair <corvus@inaugust.com>
Tested-by: Jenkins
diff --git a/doc/source/triggers.rst b/doc/source/triggers.rst
index edd9864..cbcbad2 100644
--- a/doc/source/triggers.rst
+++ b/doc/source/triggers.rst
@@ -35,3 +35,69 @@
+/-1`` and ``Submit`` to the user. Additional categories or values may
be added to Gerrit. Zuul is very flexible and can take advantage of
those.
+
+Zuul References
+~~~~~~~~~~~~~~~
+
+As the DependentPipelineManager may combine several changes together
+for testing when performing speculative execution, determining exactly
+how the workspace should be set up when running a Job can be complex.
+To alleviate this problem, Zuul performs merges itself, merging or
+cherry-picking changes as required and identifies the result with a
+Git reference of the form ``refs/zuul/<branch>/Z<random sha1>``.
+Preparing the workspace is then a simple matter of fetching that ref
+and checking it out. The parameters that provide this information are
+described in :ref:`launchers`.
+
+These references need to be made available via a Git repository that
+is available to Jenkins. You may accomplish this by either allowing
+Zuul to push the references back to Gerrit, in which case you may
+simply use the Gerrit Git repository. If you do not have access to
+the Gerrit repository, or would prefer Zuul not push its refs there,
+you may directly serve the Git repositories that Zuul uses, and
+configure Jenkins to use those. Instructions for each of these
+alternatives are in the following sections.
+
+Pushing to Gerrit
+"""""""""""""""""
+
+If you want to push Zuul refs back to Gerrit, set the following
+permissions for your project (or ``All-Projects``) in Gerrit (where
+``CI Tools`` is a group of which the user you created above is a
+member)::
+
+ [access "refs/zuul/*"]
+ create = group CI Tools
+ push = +force CI Tools
+ pushMerge = group CI Tools
+ [access "refs/for/refs/zuul/*"]
+ pushMerge = group CI Tools
+
+And set ``push_change_refs`` to ``true`` in the ``zuul`` section of
+zuul.conf.
+
+Serving Zuul Git Repos
+""""""""""""""""""""""
+
+Zuul maintains its own copies of any needed Git repositories in the
+directory specified by ``git_dir`` in the ``zuul`` section of
+zuul.conf (by default, /var/lib/zuul/git). If you want to serve
+Zuul's Git repositories in order to provide Zuul refs for Jenkins, you
+can configure Apache to do so using the following directives::
+
+ SetEnv GIT_PROJECT_ROOT /var/lib/zuul/git
+ SetEnv GIT_HTTP_EXPORT_ALL
+
+ AliasMatch ^/p/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/lib/zuul/git/$1
+ AliasMatch ^/p/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/lib/zuul/git/$1
+ ScriptAlias /p/ /usr/lib/git-core/git-http-backend/
+
+And set ``push_change_refs`` to ``false`` (the default) in the
+``zuul`` section of zuul.conf.
+
+Note that Zuul's Git repositories are not bare, which means they have
+a working tree, and are not suitable for public consumption (for
+instance, a clone will produce a repository in an unpredictable state
+depending on what the state of Zuul's repository is when the clone
+happens). They are, however, suitable for automated systems that
+respond to Zuul triggers.