blob: 4c445c685caa535d8d364c781eb7f9454a595114 [file] [log] [blame]
James E. Blair4076e2b2014-01-28 12:42:20 -08001:title: Merger
2
3Merger
4======
5
6The Zuul Merger is a separate component which communicates with the
7main Zuul server via Gearman. Its purpose is to speculatively merge
8the changes for Zuul in preparation for testing. The resulting git
9commits also must be served to the test workers, and the server(s)
10running the Zuul Merger are expected to do this as well. Because both
11of these tasks are resource intensive, any number of Zuul Mergers can
12be run in parallel on distinct hosts.
13
14Configuration
15~~~~~~~~~~~~~
16
17The Zuul Merger can read the same zuul.conf file as the main Zuul
18server and requires the ``gearman``, ``gerrit``, ``merger``, and
19``zuul`` sections (indicated fields only). Be sure the zuul_url is
20set appropriately on each host that runs a zuul-merger.
21
22Zuul References
23~~~~~~~~~~~~~~~
24
25As the DependentPipelineManager may combine several changes together
26for testing when performing speculative execution, determining exactly
27how the workspace should be set up when running a Job can be complex.
28To alleviate this problem, Zuul performs merges itself, merging or
29cherry-picking changes as required and identifies the result with a
30Git reference of the form ``refs/zuul/<branch>/Z<random sha1>``.
31Preparing the workspace is then a simple matter of fetching that ref
32and checking it out. The parameters that provide this information are
33described in :ref:`launchers`.
34
35These references need to be made available via a Git repository that
36is available to Jenkins. This is accomplished by serving Zuul's Git
37repositories directly.
38
39Serving Zuul Git Repos
40~~~~~~~~~~~~~~~~~~~~~~
41
42Zuul maintains its own copies of any needed Git repositories in the
43directory specified by ``git_dir`` in the ``merger`` section of
44zuul.conf (by default, /var/lib/zuul/git). To directly serve Zuul's
45Git repositories in order to provide Zuul refs for Jenkins, you can
46configure Apache to do so using the following directives::
47
48 SetEnv GIT_PROJECT_ROOT /var/lib/zuul/git
49 SetEnv GIT_HTTP_EXPORT_ALL
50
51 AliasMatch ^/p/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/lib/zuul/git/$1
52 AliasMatch ^/p/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/lib/zuul/git/$1
53 ScriptAlias /p/ /usr/lib/git-core/git-http-backend/
54
55And set ``push_change_refs`` to ``false`` (the default) in the
56``zuul`` section of zuul.conf.
57
58Note that Zuul's Git repositories are not bare, which means they have
59a working tree, and are not suitable for public consumption (for
60instance, a clone will produce a repository in an unpredictable state
61depending on what the state of Zuul's repository is when the clone
62happens). They are, however, suitable for automated systems that
63respond to Zuul triggers.