blob: cd342c3ba713c0966d212aae0fde8b4b39336824 [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
Gregory Haynes4fc12542015-04-22 20:38:06 -07007merged. Zuul supports Gerrit and GitHub as triggering systems.
James E. Blaircdd00072012-06-08 19:17:28 -07008Zuul's design is modular, so alternate triggering and reporting
James E. Blair63bb0ef2013-07-29 17:14:51 -07009systems can be supported.
James E. Blaircdd00072012-06-08 19:17:28 -070010
11Gerrit
12------
13
14Zuul works with standard versions of Gerrit by invoking the ``gerrit
15stream-events`` command over an SSH connection. It also reports back
16to Gerrit using SSH.
17
David Pursehouse78556f72014-11-04 18:44:36 +090018If using Gerrit 2.7 or later, make sure the user is a member of a group
19that is granted the ``Stream Events`` permission, otherwise it will not
20be able to invoke the ``gerrit stream-events`` command over SSH.
21
Joshua Heskethfe485c62015-08-11 23:42:34 +100022A connection name with the gerrit driver can take multiple events with
23the following options.
24
25 **event**
26 The event name from gerrit. Examples: ``patchset-created``,
27 ``comment-added``, ``ref-updated``. This field is treated as a
28 regular expression.
29
30 **branch**
31 The branch associated with the event. Example: ``master``. This
32 field is treated as a regular expression, and multiple branches may
33 be listed.
34
35 **ref**
36 On ref-updated events, the branch parameter is not used, instead the
37 ref is provided. Currently Gerrit has the somewhat idiosyncratic
38 behavior of specifying bare refs for branch names (e.g., ``master``),
39 but full ref names for other kinds of refs (e.g., ``refs/tags/foo``).
40 Zuul matches what you put here exactly against what Gerrit
41 provides. This field is treated as a regular expression, and
42 multiple refs may be listed.
43
44 **ignore-deletes**
45 When a branch is deleted, a ref-updated event is emitted with a newrev
46 of all zeros specified. The ``ignore-deletes`` field is a boolean value
47 that describes whether or not these newrevs trigger ref-updated events.
48 The default is True, which will not trigger ref-updated events.
49
50 **approval**
51 This is only used for ``comment-added`` events. It only matches if
52 the event has a matching approval associated with it. Example:
53 ``code-review: 2`` matches a ``+2`` vote on the code review category.
54 Multiple approvals may be listed.
55
56 **email**
57 This is used for any event. It takes a regex applied on the performer
58 email, i.e. Gerrit account email address. If you want to specify
59 several email filters, you must use a YAML list. Make sure to use non
60 greedy matchers and to escapes dots!
61 Example: ``email: ^.*?@example\.org$``.
62
63 **email_filter** (deprecated)
64 A deprecated alternate spelling of *email*. Only one of *email* or
65 *email_filter* should be used.
66
67 **username**
68 This is used for any event. It takes a regex applied on the performer
69 username, i.e. Gerrit account name. If you want to specify several
70 username filters, you must use a YAML list. Make sure to use non greedy
71 matchers and to escapes dots!
72 Example: ``username: ^jenkins$``.
73
74 **username_filter** (deprecated)
75 A deprecated alternate spelling of *username*. Only one of *username* or
76 *username_filter* should be used.
77
78 **comment**
79 This is only used for ``comment-added`` events. It accepts a list of
80 regexes that are searched for in the comment string. If any of these
81 regexes matches a portion of the comment string the trigger is
82 matched. ``comment: retrigger`` will match when comments
83 containing 'retrigger' somewhere in the comment text are added to a
84 change.
85
86 **comment_filter** (deprecated)
87 A deprecated alternate spelling of *comment*. Only one of *comment* or
88 *comment_filter* should be used.
89
90 *require-approval*
91 This may be used for any event. It requires that a certain kind
92 of approval be present for the current patchset of the change (the
93 approval could be added by the event in question). It follows the
94 same syntax as the :ref:`"approval" pipeline requirement
95 <pipeline-require-approval>`. For each specified criteria there must
96 exist a matching approval.
97
98 *reject-approval*
99 This takes a list of approvals in the same format as
100 *require-approval* but will fail to enter the pipeline if there is
101 a matching approval.
102
Gregory Haynes4fc12542015-04-22 20:38:06 -0700103GitHub
104------
105
106Github webhook events can be configured as triggers.
107
108A connection name with the github driver can take multiple events with the
109following options.
110
111 **event**
112 The pull request event from github. A ``pull_request`` event will
113 have associated action(s) to trigger from. The supported actions are:
114
115 *opened* - pull request opened
116
117 *changed* - pull request synchronized
118
119 *closed* - pull request closed
120
121 *reopened* - pull request reopened
122
Jan Hrubanc7ab1602015-10-14 15:29:33 +0200123 *comment* - comment added on pull request
124
125 **comment**
126 This is only used for ``pull_request`` ``comment`` events. It accepts a list
127 of regexes that are searched for in the comment string. If any of these
128 regexes matches a portion of the comment string the trigger is matched.
129 ``comment: retrigger`` will match when comments containing 'retrigger'
130 somewhere in the comment text are added to a pull request.
131
Wayne1a78c612015-06-11 17:14:13 -0700132 Additionally a ``push`` event can be configured, with an
133 associated ``ref`` represented as a regex to match branches or tags.
134
Gregory Haynes4fc12542015-04-22 20:38:06 -0700135GitHub Configuration
136~~~~~~~~~~~~~~~~~~~~
137
138Configure GitHub `webhook events
139<https://developer.github.com/webhooks/creating/>`_.
140
141Set *Payload URL* to
142``http://<zuul-hostname>/connection/<connection-name>/payload``.
143
144Set *Content Type* to ``application/json``.
145
146Select *Events* you are interested in. See above for the supported events.
Joshua Heskethfe485c62015-08-11 23:42:34 +1000147
James E. Blair63bb0ef2013-07-29 17:14:51 -0700148Timer
149-----
150
151A simple timer trigger is available as well. It supports triggering
152jobs in a pipeline based on cron-style time instructions.
James E. Blairc494d542014-08-06 09:23:52 -0700153
Joshua Heskethfe485c62015-08-11 23:42:34 +1000154Timers don't require a special connection or driver. Instead they can
155be used by listing **timer** as the trigger.
156
157This trigger will run based on a cron-style time specification.
158It will enqueue an event into its pipeline for every project
159defined in the configuration. Any job associated with the
160pipeline will run in response to that event.
161
162 **time**
163 The time specification in cron syntax. Only the 5 part syntax is
164 supported, not the symbolic names. Example: ``0 0 * * *`` runs
165 at midnight.
166
James E. Blairc494d542014-08-06 09:23:52 -0700167Zuul
168----
169
170The Zuul trigger generates events based on internal actions in Zuul.
Joshua Heskethfe485c62015-08-11 23:42:34 +1000171Multiple events may be listed.
172
173Zuul events don't require a special connection or driver. Instead they
174can be used by listing **zuul** as the trigger.
175
176 **event**
177 The event name. Currently supported:
178
179 *project-change-merged* when Zuul merges a change to a project,
180 it generates this event for every open change in the project.
181
182 *parent-change-enqueued* when Zuul enqueues a change into any
183 pipeline, it generates this event for every child of that
184 change.
185
186 **pipeline**
187 Only available for ``parent-change-enqueued`` events. This is the
188 name of the pipeline in which the parent change was enqueued.
189
190 *require-approval*
191 This may be used for any event. It requires that a certain kind
192 of approval be present for the current patchset of the change (the
193 approval could be added by the event in question). It follows the
194 same syntax as the :ref:`"approval" pipeline requirement
195 <pipeline-require-approval>`. For each specified criteria there must
196 exist a matching approval.
197
198 *reject-approval*
199 This takes a list of approvals in the same format as
200 *require-approval* but will fail to enter the pipeline if there is
Gregory Haynes4fc12542015-04-22 20:38:06 -0700201 a matching approval.