James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 1 | :title: Triggers |
| 2 | |
| 3 | Triggers |
| 4 | ======== |
| 5 | |
| 6 | The process of merging a change starts with proposing a change to be |
Gregory Haynes | 4fc1254 | 2015-04-22 20:38:06 -0700 | [diff] [blame] | 7 | merged. Zuul supports Gerrit and GitHub as triggering systems. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 8 | Zuul's design is modular, so alternate triggering and reporting |
James E. Blair | 63bb0ef | 2013-07-29 17:14:51 -0700 | [diff] [blame] | 9 | systems can be supported. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 10 | |
| 11 | Gerrit |
| 12 | ------ |
| 13 | |
| 14 | Zuul works with standard versions of Gerrit by invoking the ``gerrit |
| 15 | stream-events`` command over an SSH connection. It also reports back |
| 16 | to Gerrit using SSH. |
| 17 | |
David Pursehouse | 78556f7 | 2014-11-04 18:44:36 +0900 | [diff] [blame] | 18 | If using Gerrit 2.7 or later, make sure the user is a member of a group |
| 19 | that is granted the ``Stream Events`` permission, otherwise it will not |
| 20 | be able to invoke the ``gerrit stream-events`` command over SSH. |
| 21 | |
Joshua Hesketh | fe485c6 | 2015-08-11 23:42:34 +1000 | [diff] [blame] | 22 | A connection name with the gerrit driver can take multiple events with |
| 23 | the 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 Haynes | 4fc1254 | 2015-04-22 20:38:06 -0700 | [diff] [blame] | 103 | GitHub |
| 104 | ------ |
| 105 | |
| 106 | Github webhook events can be configured as triggers. |
| 107 | |
| 108 | A connection name with the github driver can take multiple events with the |
| 109 | following 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 Hruban | c7ab160 | 2015-10-14 15:29:33 +0200 | [diff] [blame^] | 123 | *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 | |
Wayne | 1a78c61 | 2015-06-11 17:14:13 -0700 | [diff] [blame] | 132 | Additionally a ``push`` event can be configured, with an |
| 133 | associated ``ref`` represented as a regex to match branches or tags. |
| 134 | |
Gregory Haynes | 4fc1254 | 2015-04-22 20:38:06 -0700 | [diff] [blame] | 135 | GitHub Configuration |
| 136 | ~~~~~~~~~~~~~~~~~~~~ |
| 137 | |
| 138 | Configure GitHub `webhook events |
| 139 | <https://developer.github.com/webhooks/creating/>`_. |
| 140 | |
| 141 | Set *Payload URL* to |
| 142 | ``http://<zuul-hostname>/connection/<connection-name>/payload``. |
| 143 | |
| 144 | Set *Content Type* to ``application/json``. |
| 145 | |
| 146 | Select *Events* you are interested in. See above for the supported events. |
Joshua Hesketh | fe485c6 | 2015-08-11 23:42:34 +1000 | [diff] [blame] | 147 | |
James E. Blair | 63bb0ef | 2013-07-29 17:14:51 -0700 | [diff] [blame] | 148 | Timer |
| 149 | ----- |
| 150 | |
| 151 | A simple timer trigger is available as well. It supports triggering |
| 152 | jobs in a pipeline based on cron-style time instructions. |
James E. Blair | c494d54 | 2014-08-06 09:23:52 -0700 | [diff] [blame] | 153 | |
Joshua Hesketh | fe485c6 | 2015-08-11 23:42:34 +1000 | [diff] [blame] | 154 | Timers don't require a special connection or driver. Instead they can |
| 155 | be used by listing **timer** as the trigger. |
| 156 | |
| 157 | This trigger will run based on a cron-style time specification. |
| 158 | It will enqueue an event into its pipeline for every project |
| 159 | defined in the configuration. Any job associated with the |
| 160 | pipeline 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. Blair | c494d54 | 2014-08-06 09:23:52 -0700 | [diff] [blame] | 167 | Zuul |
| 168 | ---- |
| 169 | |
| 170 | The Zuul trigger generates events based on internal actions in Zuul. |
Joshua Hesketh | fe485c6 | 2015-08-11 23:42:34 +1000 | [diff] [blame] | 171 | Multiple events may be listed. |
| 172 | |
| 173 | Zuul events don't require a special connection or driver. Instead they |
| 174 | can 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 Haynes | 4fc1254 | 2015-04-22 20:38:06 -0700 | [diff] [blame] | 201 | a matching approval. |