110 lines
4.2 KiB
ReStructuredText
110 lines
4.2 KiB
ReStructuredText
:title: Triggers
|
|
|
|
Triggers
|
|
========
|
|
|
|
The process of merging a change starts with proposing a change to be
|
|
merged. Primarily, Zuul supports Gerrit as a triggering system, as
|
|
well as a facility for triggering jobs based on a timer.
|
|
Zuul's design is modular, so alternate triggering and reporting
|
|
systems can be supported.
|
|
|
|
Gerrit
|
|
------
|
|
|
|
Zuul works with standard versions of Gerrit by invoking the ``gerrit
|
|
stream-events`` command over an SSH connection. It also reports back
|
|
to Gerrit using SSH.
|
|
|
|
Gerrit Configuration
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Zuul will need access to a Gerrit user. Consider naming the user
|
|
*Jenkins* so that developers see that feedback from changes is from
|
|
Jenkins (Zuul attempts to stay out of the way of developers, most
|
|
shouldn't even need to know it's there).
|
|
|
|
Create an SSH keypair for Zuul to use if there isn't one already, and
|
|
create a Gerrit user with that key::
|
|
|
|
cat ~/id_rsa.pub | ssh -p29418 gerrit.example.com gerrit create-account --ssh-key - --full-name Jenkins jenkins
|
|
|
|
Give that user whatever permissions will be needed on the projects you
|
|
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/<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
|
|
forgeAuthor = 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.
|
|
|
|
Timer
|
|
-----
|
|
|
|
A simple timer trigger is available as well. It supports triggering
|
|
jobs in a pipeline based on cron-style time instructions.
|