zuul/doc/source/merger.rst

title

Merger

Merger

The Zuul Merger is a separate component which communicates with the main Zuul server via Gearman. Its purpose is to speculatively merge the changes for Zuul in preparation for testing. The resulting git commits also must be served to the test workers, and the server(s) running the Zuul Merger are expected to do this as well. Because both of these tasks are resource intensive, any number of Zuul Mergers can be run in parallel on distinct hosts.

Configuration

The Zuul Merger can read the same zuul.conf file as the main Zuul server and requires the gearman, gerrit, merger, and zuul sections (indicated fields only). Be sure the zuul_url is set appropriately on each host that runs a zuul-merger.

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 launchers.

These references need to be made available via a Git repository that is available to workers (such as Jenkins). This is accomplished by serving Zuul's Git repositories directly.

Serving Zuul Git Repos

Zuul maintains its own copies of any needed Git repositories in the directory specified by git_dir in the merger section of zuul.conf (by default, /var/lib/zuul/git). To directly serve Zuul's Git repositories in order to provide Zuul refs for workers, 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/

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.