From 172c076a1b3d7863ebcf7854cc90ed3838fb2de3 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Tue, 2 Oct 2012 15:35:54 -0700 Subject: [PATCH] Add documentation about serving Zuul refs. Change-Id: I6cdd20e6238fafdca626eb2531a3a78c985bb680 Reviewed-on: https://review.openstack.org/13974 Reviewed-by: Clark Boylan Approved: James E. Blair Tested-by: Jenkins --- doc/source/launchers.rst | 1 + doc/source/triggers.rst | 66 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/doc/source/launchers.rst b/doc/source/launchers.rst index ff818be5d7..34aa4eac74 100644 --- a/doc/source/launchers.rst +++ b/doc/source/launchers.rst @@ -1,3 +1,4 @@ +.. _launchers: :title: Launchers Launchers diff --git a/doc/source/triggers.rst b/doc/source/triggers.rst index edd98646d7..cbcbad2378 100644 --- a/doc/source/triggers.rst +++ b/doc/source/triggers.rst @@ -35,3 +35,69 @@ want Zuul to gate. For instance, you may want to grant ``Verified +/-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//Z``. +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.