blob: 0bd07de0f0bc8956e23adb5bcab6cf28850f6a3c [file] [log] [blame]
James E. Blaircdd00072012-06-08 19:17:28 -07001:title: Triggers
2
3Triggers
4========
5
6The process of merging a change starts with proposing a change to be
James E. Blair63bb0ef2013-07-29 17:14:51 -07007merged. Primarily, Zuul supports Gerrit as a triggering system, as
8well as a facility for triggering jobs based on a timer.
James E. Blaircdd00072012-06-08 19:17:28 -07009Zuul's design is modular, so alternate triggering and reporting
James E. Blair63bb0ef2013-07-29 17:14:51 -070010systems can be supported.
James E. Blaircdd00072012-06-08 19:17:28 -070011
12Gerrit
13------
14
15Zuul works with standard versions of Gerrit by invoking the ``gerrit
16stream-events`` command over an SSH connection. It also reports back
17to Gerrit using SSH.
18
19Gerrit Configuration
20~~~~~~~~~~~~~~~~~~~~
21
22Zuul will need access to a Gerrit user. Consider naming the user
23*Jenkins* so that developers see that feedback from changes is from
24Jenkins (Zuul attempts to stay out of the way of developers, most
25shouldn't even need to know it's there).
26
27Create an SSH keypair for Zuul to use if there isn't one already, and
28create a Gerrit user with that key::
29
30 cat ~/id_rsa.pub | ssh -p29418 gerrit.example.com gerrit create-account --ssh-key - --full-name Jenkins jenkins
31
32Give that user whatever permissions will be needed on the projects you
33want Zuul to gate. For instance, you may want to grant ``Verified
34+/-1`` and ``Submit`` to the user. Additional categories or values may
35be added to Gerrit. Zuul is very flexible and can take advantage of
36those.
James E. Blair172c0762012-10-02 15:35:54 -070037
38Zuul References
39~~~~~~~~~~~~~~~
40
41As the DependentPipelineManager may combine several changes together
42for testing when performing speculative execution, determining exactly
43how the workspace should be set up when running a Job can be complex.
44To alleviate this problem, Zuul performs merges itself, merging or
45cherry-picking changes as required and identifies the result with a
46Git reference of the form ``refs/zuul/<branch>/Z<random sha1>``.
47Preparing the workspace is then a simple matter of fetching that ref
48and checking it out. The parameters that provide this information are
49described in :ref:`launchers`.
50
51These references need to be made available via a Git repository that
52is available to Jenkins. You may accomplish this by either allowing
53Zuul to push the references back to Gerrit, in which case you may
54simply use the Gerrit Git repository. If you do not have access to
55the Gerrit repository, or would prefer Zuul not push its refs there,
56you may directly serve the Git repositories that Zuul uses, and
57configure Jenkins to use those. Instructions for each of these
58alternatives are in the following sections.
59
60Pushing to Gerrit
61"""""""""""""""""
62
63If you want to push Zuul refs back to Gerrit, set the following
64permissions for your project (or ``All-Projects``) in Gerrit (where
65``CI Tools`` is a group of which the user you created above is a
66member)::
67
68 [access "refs/zuul/*"]
69 create = group CI Tools
70 push = +force CI Tools
71 pushMerge = group CI Tools
72 [access "refs/for/refs/zuul/*"]
73 pushMerge = group CI Tools
74
75And set ``push_change_refs`` to ``true`` in the ``zuul`` section of
76zuul.conf.
77
78Serving Zuul Git Repos
79""""""""""""""""""""""
80
81Zuul maintains its own copies of any needed Git repositories in the
82directory specified by ``git_dir`` in the ``zuul`` section of
83zuul.conf (by default, /var/lib/zuul/git). If you want to serve
84Zuul's Git repositories in order to provide Zuul refs for Jenkins, you
85can configure Apache to do so using the following directives::
86
87 SetEnv GIT_PROJECT_ROOT /var/lib/zuul/git
88 SetEnv GIT_HTTP_EXPORT_ALL
89
90 AliasMatch ^/p/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/lib/zuul/git/$1
91 AliasMatch ^/p/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/lib/zuul/git/$1
92 ScriptAlias /p/ /usr/lib/git-core/git-http-backend/
93
94And set ``push_change_refs`` to ``false`` (the default) in the
95``zuul`` section of zuul.conf.
96
97Note that Zuul's Git repositories are not bare, which means they have
98a working tree, and are not suitable for public consumption (for
99instance, a clone will produce a repository in an unpredictable state
100depending on what the state of Zuul's repository is when the clone
101happens). They are, however, suitable for automated systems that
102respond to Zuul triggers.
James E. Blair63bb0ef2013-07-29 17:14:51 -0700103
104Timer
105-----
106
107A simple timer trigger is available as well. It supports triggering
108jobs in a pipeline based on cron-style time instructions.