James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 1 | :title: Launchers |
| 2 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 3 | .. _Gearman: http://gearman.org/ |
Antoine Musso | d06f2a6 | 2012-11-16 17:40:58 +0100 | [diff] [blame] | 4 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 5 | .. _`Gearman Plugin`: |
| 6 | https://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin |
| 7 | |
Joshua Hesketh | 6a0a618 | 2014-03-13 13:23:30 +1100 | [diff] [blame] | 8 | .. _`Turbo-Hipster`: |
Andreas Jaeger | e1ba776 | 2016-06-03 15:08:25 +0200 | [diff] [blame] | 9 | https://git.openstack.org/cgit/openstack/turbo-hipster/ |
Joshua Hesketh | 6a0a618 | 2014-03-13 13:23:30 +1100 | [diff] [blame] | 10 | |
| 11 | .. _`Turbo-Hipster Documentation`: |
| 12 | http://turbo-hipster.rtfd.org/ |
| 13 | |
Joshua Hesketh | 36c3fa5 | 2014-01-22 11:40:52 +1100 | [diff] [blame] | 14 | .. _FormPost: http://docs.openstack.org/developer/swift/misc.html#module-swift.common.middleware.formpost |
| 15 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 16 | .. _launchers: |
Antoine Musso | d06f2a6 | 2012-11-16 17:40:58 +0100 | [diff] [blame] | 17 | |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 18 | Launchers |
| 19 | ========= |
| 20 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 21 | Zuul has a modular architecture for launching jobs. Currently, the |
| 22 | only supported module interfaces with Gearman_. This design allows |
| 23 | any system to run jobs for Zuul simply by interfacing with a Gearman |
| 24 | server. The recommended way of integrating a new job-runner with Zuul |
| 25 | is via this method. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 26 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 27 | If Gearman is unsuitable, Zuul may be extended with a new launcher |
| 28 | module. Zuul makes very few assumptions about the interface to a |
| 29 | launcher -- if it can trigger jobs, cancel them, and receive success |
| 30 | or failure reports, it should be able to be used with Zuul. Patches |
| 31 | to this effect are welcome. |
| 32 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 33 | Zuul Parameters |
| 34 | --------------- |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 35 | |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 36 | Zuul will pass some parameters with every job it launches. These are |
| 37 | for workers to be able to get the repositories into the state they are |
| 38 | intended to be tested in. Builds can be triggered either by an action |
| 39 | on a change or by a reference update. Both events share a common set |
| 40 | of parameters and more specific parameters as follows: |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 41 | |
| 42 | Common parameters |
| 43 | ~~~~~~~~~~~~~~~~~ |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 44 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 45 | **ZUUL_UUID** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 46 | Zuul provided key to link builds with Gerrit events. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 47 | **ZUUL_REF** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 48 | Zuul provided ref that includes commit(s) to build. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 49 | **ZUUL_COMMIT** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 50 | The commit SHA1 at the head of ZUUL_REF. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 51 | **ZUUL_PROJECT** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 52 | The project that triggered this build. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 53 | **ZUUL_PIPELINE** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 54 | The Zuul pipeline that is building this job. |
Arx Cruz | b1b010d | 2013-10-28 19:49:59 -0200 | [diff] [blame] | 55 | **ZUUL_URL** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 56 | The URL for the zuul server as configured in zuul.conf. |
Joshua Hesketh | ba8776a | 2014-01-12 14:35:40 +0800 | [diff] [blame] | 57 | A test runner may use this URL as the basis for fetching |
Arx Cruz | b1b010d | 2013-10-28 19:49:59 -0200 | [diff] [blame] | 58 | git commits. |
Joshua Hesketh | 6c21dd1 | 2014-03-31 12:23:21 +1100 | [diff] [blame] | 59 | **BASE_LOG_PATH** |
| 60 | zuul suggests a path to store and address logs. This is deterministic |
| 61 | and hence useful for where you want workers to upload to a specific |
| 62 | destination or need them to have a specific final URL you can link to |
| 63 | in advanced. For changes it is: |
| 64 | "last-two-digits-of-change/change-number/patchset-number". |
| 65 | For reference updates it is: "first-two-digits-of-newrev/newrev" |
| 66 | **LOG_PATH** |
| 67 | zuul also suggests a unique path for logs to the worker. This is |
| 68 | "BASE_LOG_PATH/pipeline-name/job-name/uuid" |
James E. Blair | 5821bd9 | 2015-09-16 08:48:15 -0700 | [diff] [blame] | 69 | **ZUUL_VOTING** |
| 70 | Whether Zuul considers this job voting or not. Note that if Zuul is |
| 71 | reconfigured during the run, the voting status of a job may change |
| 72 | and this value will be out of date. Values are '1' if voting, '0' |
| 73 | otherwise. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 74 | |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 75 | Change related parameters |
| 76 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 77 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 78 | The following additional parameters will only be provided for builds |
| 79 | associated with changes (i.e., in response to patchset-created or |
| 80 | comment-added events): |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 81 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 82 | **ZUUL_BRANCH** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 83 | The target branch for the change that triggered this build. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 84 | **ZUUL_CHANGE** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 85 | The Gerrit change ID for the change that triggered this build. |
Julia Kreger | 012c1c5 | 2015-04-21 20:11:39 -0400 | [diff] [blame] | 86 | **ZUUL_CHANGES** |
| 87 | A caret character separated list of the changes upon which this build |
| 88 | is dependent upon in the form of a colon character separated list |
| 89 | consisting of project name, target branch, and revision ref. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 90 | **ZUUL_CHANGE_IDS** |
| 91 | All of the Gerrit change IDs that are included in this build (useful |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 92 | when the DependentPipelineManager combines changes for testing). |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 93 | **ZUUL_PATCHSET** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 94 | The Gerrit patchset number for the change that triggered this build. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 95 | |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 96 | Reference updated parameters |
| 97 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 98 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 99 | The following additional parameters will only be provided for |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 100 | post-merge (ref-updated) builds: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 101 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 102 | **ZUUL_OLDREV** |
| 103 | The SHA1 of the old revision at this ref (recall the ref name is |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 104 | in ZUUL_REF). |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 105 | **ZUUL_NEWREV** |
| 106 | The SHA1 of the new revision at this ref (recall the ref name is |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 107 | in ZUUL_REF). |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 108 | **ZUUL_SHORT_OLDREV** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 109 | The shortened (7 character) SHA1 of the old revision. |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 110 | **ZUUL_SHORT_NEWREV** |
Łukasz Jernaś | 048acb4 | 2014-03-02 18:49:41 +0100 | [diff] [blame] | 111 | The shortened (7 character) SHA1 of the new revision. |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 112 | |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 113 | Unset revisions default to 00000000000000000000000000000000. |
| 114 | |
| 115 | Examples: |
| 116 | |
| 117 | When a reference is created:: |
| 118 | |
| 119 | ZUUL_OLDREV=00000000000000000000000000000000 |
| 120 | ZUUL_NEWREV=123456789abcdef123456789abcdef12 |
| 121 | ZUUL_SHORT_OLDREV=0000000 |
| 122 | ZUUL_SHORT_NEWREV=1234567 |
| 123 | |
| 124 | When a reference is deleted:: |
| 125 | |
| 126 | ZUUL_OLDREV=123456789abcdef123456789abcdef12 |
| 127 | ZUUL_NEWREV=00000000000000000000000000000000 |
| 128 | ZUUL_SHORT_OLDREV=1234567 |
| 129 | ZUUL_SHORT_NEWREV=0000000 |
| 130 | |
| 131 | And finally a reference being altered:: |
| 132 | |
| 133 | ZUUL_OLDREV=123456789abcdef123456789abcdef12 |
| 134 | ZUUL_NEWREV=abcdef123456789abcdef123456789ab |
| 135 | ZUUL_SHORT_OLDREV=1234567 |
| 136 | ZUUL_SHORT_NEWREV=abcdef1 |
| 137 | |
| 138 | Your jobs can check whether the parameters are ``000000`` to act |
| 139 | differently on each kind of event. |
| 140 | |
Joshua Hesketh | 36c3fa5 | 2014-01-22 11:40:52 +1100 | [diff] [blame] | 141 | Swift parameters |
| 142 | ~~~~~~~~~~~~~~~~ |
| 143 | |
| 144 | If swift information has been configured for the job zuul will also |
| 145 | provide signed credentials for the builder to upload results and |
| 146 | assets into containers using the `FormPost`_ middleware. |
| 147 | |
| 148 | Each zuul container/instruction set will contain each of the following |
| 149 | parameters where $NAME is the ``name`` defined in the layout. |
| 150 | |
| 151 | *SWIFT_$NAME_URL* |
| 152 | The swift destination URL. This will be the entire URL including |
| 153 | the AUTH, container and path prefix (folder). |
| 154 | *SWIFT_$NAME_HMAC_BODY* |
| 155 | The information signed in the HMAC body. The body is as follows:: |
| 156 | |
| 157 | PATH TO OBJECT PREFIX (excluding domain) |
| 158 | BLANK LINE (zuul implements no form redirect) |
| 159 | MAX FILE SIZE |
| 160 | MAX FILE COUNT |
| 161 | SIGNATURE EXPIRY |
| 162 | |
| 163 | *SWIFT_$NAME_SIGNATURE* |
| 164 | The HMAC body signed with the configured key. |
| 165 | *SWIFT_$NAME_LOGSERVER_PREFIX* |
| 166 | The URL to prepend to the object path when returning the results |
| 167 | from a build. |
| 168 | |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 169 | Gearman |
| 170 | ------- |
| 171 | |
| 172 | Gearman_ is a general-purpose protocol for distributing jobs to any |
| 173 | number of workers. Zuul works with Gearman by sending specific |
| 174 | information with job requests to Gearman, and expects certain |
| 175 | information to be returned on completion. This protocol is described |
| 176 | in `Zuul-Gearman Protocol`_. |
| 177 | |
| 178 | In order for Zuul to run any jobs, you will need a running Gearman |
| 179 | server. Zuul includes a Gearman server, and it is recommended that it |
| 180 | be used as it supports the following features needed by Zuul: |
| 181 | |
| 182 | * Canceling jobs in the queue (admin protocol command "cancel job"). |
| 183 | * Strict FIFO queue operation (gearmand's round-robin mode may be |
| 184 | sufficient, but is untested). |
| 185 | |
| 186 | To enable the built-in server, see the ``gearman_server`` section of |
| 187 | ``zuul.conf``. Be sure that the host allows connections from Zuul and |
| 188 | any workers (e.g., Jenkins masters) on TCP port 4730, and nowhere else |
| 189 | (as the Gearman protocol does not include any provision for |
| 190 | authentication). |
| 191 | |
| 192 | Gearman Jenkins Plugin |
| 193 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 194 | |
| 195 | The `Gearman Jenkins Plugin`_ makes it easy to use Jenkins with Zuul |
| 196 | by providing an interface between Jenkins and Gearman. In this |
| 197 | configuration, Zuul asks Gearman to run jobs, and Gearman can then |
| 198 | distribute those jobs to any number of Jenkins systems (including |
| 199 | multiple Jenkins masters). |
| 200 | |
| 201 | The `Gearman Plugin`_ can be installed in Jenkins in order to |
| 202 | facilitate Jenkins running jobs for Zuul. Install the plugin and |
| 203 | configure it with the hostname or IP address of your Gearman server |
| 204 | and the port on which it is listening (4730 by default). It will |
| 205 | automatically register all known Jenkins jobs as functions that Zuul |
| 206 | can invoke via Gearman. |
| 207 | |
| 208 | Any number of masters can be configured in this way, and Gearman will |
| 209 | distribute jobs to all of them as appropriate. |
| 210 | |
| 211 | No special Jenkins job configuration is needed to support triggering |
| 212 | by Zuul. |
| 213 | |
| 214 | The Gearman Plugin will ensure the `Zuul Parameters`_ are supplied as |
| 215 | Jenkins build parameters, so they will be available for use in the job |
| 216 | configuration as well as to the running job as environment variables. |
| 217 | |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 218 | Jenkins git plugin configuration |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 219 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Antoine Musso | e0f5bb4 | 2014-03-04 11:30:37 +0100 | [diff] [blame] | 220 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 221 | In order to test the correct build, configure the Jenkins Git SCM |
| 222 | plugin as follows:: |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 223 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 224 | Source Code Management: |
| 225 | Git |
| 226 | Repositories: |
| 227 | Repository URL: <your Gerrit or Zuul repository URL> |
| 228 | Advanced: |
| 229 | Refspec: ${ZUUL_REF} |
| 230 | Branches to build: |
| 231 | Branch Specifier: ${ZUUL_COMMIT} |
James E. Blair | e281901 | 2013-06-28 17:17:26 -0400 | [diff] [blame] | 232 | Advanced: |
| 233 | Clean after checkout: True |
James E. Blair | cdd0007 | 2012-06-08 19:17:28 -0700 | [diff] [blame] | 234 | |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 235 | That should be sufficient for a job that only builds a single project. |
| 236 | If you have multiple interrelated projects (i.e., they share a Zuul |
| 237 | Change Queue) that are built together, you may be able to configure |
| 238 | the Git plugin to prepare them, or you may chose to use a shell script |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 239 | instead. As an example, the OpenStack project uses the following |
| 240 | script to prepare the workspace for its integration testing: |
James E. Blair | 81515ad | 2012-10-01 18:29:08 -0700 | [diff] [blame] | 241 | |
Andreas Jaeger | 2055dcd | 2015-12-29 21:47:21 +0100 | [diff] [blame] | 242 | https://git.openstack.org/cgit/openstack-infra/devstack-gate/tree/devstack-vm-gate-wrap.sh |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 243 | |
Joshua Hesketh | 6a0a618 | 2014-03-13 13:23:30 +1100 | [diff] [blame] | 244 | Turbo Hipster Worker |
| 245 | ~~~~~~~~~~~~~~~~~~~~ |
| 246 | |
| 247 | As an alternative to Jenkins, `Turbo-Hipster`_ is a small python |
| 248 | project designed specifically as a zuul job worker which can be |
| 249 | registered with gearman as a job runner. Please see the |
| 250 | `Turbo-Hipster Documentation`_ for details on how to set it up. |
| 251 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 252 | Zuul-Gearman Protocol |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 253 | ~~~~~~~~~~~~~~~~~~~~~ |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 254 | |
| 255 | This section is only relevant if you intend to implement a new kind of |
| 256 | worker that runs jobs for Zuul via Gearman. If you just want to use |
| 257 | Jenkins, see `Gearman Jenkins Plugin`_ instead. |
| 258 | |
| 259 | The Zuul protocol as used with Gearman is as follows: |
| 260 | |
| 261 | Starting Builds |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 262 | ^^^^^^^^^^^^^^^ |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 263 | |
| 264 | To start a build, Zuul invokes a Gearman function with the following |
| 265 | format: |
| 266 | |
| 267 | build:FUNCTION_NAME |
| 268 | |
| 269 | where **FUNCTION_NAME** is the name of the job that should be run. If |
| 270 | the job should run on a specific node (or class of node), Zuul will |
| 271 | instead invoke: |
| 272 | |
| 273 | build:FUNCTION_NAME:NODE_NAME |
| 274 | |
| 275 | where **NODE_NAME** is the name or class of node on which the job |
Paul Belanger | f36a413 | 2016-11-07 16:37:00 -0500 | [diff] [blame] | 276 | should be run. |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 277 | |
| 278 | Zuul sends the ZUUL_* parameters described in `Zuul Parameters`_ |
| 279 | encoded in JSON format as the argument included with the |
| 280 | SUBMIT_JOB_UNIQ request to Gearman. A unique ID (equal to the |
| 281 | ZUUL_UUID parameter) is also supplied to Gearman, and is accessible as |
| 282 | an added Gearman parameter with GRAB_JOB_UNIQ. |
| 283 | |
| 284 | When a Gearman worker starts running a job for Zuul, it should |
| 285 | immediately send a WORK_DATA packet with the following information |
| 286 | encoded in JSON format: |
| 287 | |
James E. Blair | 3c483cf | 2013-06-04 16:30:43 -0700 | [diff] [blame] | 288 | **name** |
| 289 | The name of the job. |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 290 | |
| 291 | **number** |
| 292 | The build number (unique to this job). |
| 293 | |
James E. Blair | 3c483cf | 2013-06-04 16:30:43 -0700 | [diff] [blame] | 294 | **manager** |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 295 | A unique identifier associated with the Gearman worker that can |
| 296 | abort this build. See `Stopping Builds`_ for more information. |
| 297 | |
James E. Blair | 3c483cf | 2013-06-04 16:30:43 -0700 | [diff] [blame] | 298 | **url** (optional) |
| 299 | The URL with the status or results of the build. Will be used in |
| 300 | the status page and the final report. |
| 301 | |
Joshua Hesketh | ba8776a | 2014-01-12 14:35:40 +0800 | [diff] [blame] | 302 | To help with debugging builds a worker may send back some optional |
| 303 | metadata: |
| 304 | |
| 305 | **worker_name** (optional) |
| 306 | The name of the worker. |
| 307 | |
| 308 | **worker_hostname** (optional) |
| 309 | The hostname of the worker. |
| 310 | |
| 311 | **worker_ips** (optional) |
| 312 | A list of IPs for the worker. |
| 313 | |
| 314 | **worker_fqdn** (optional) |
| 315 | The FQDN of the worker. |
| 316 | |
| 317 | **worker_program** (optional) |
| 318 | The program name of the worker. For example Jenkins or turbo-hipster. |
| 319 | |
| 320 | **worker_version** (optional) |
| 321 | The version of the software running the job. |
| 322 | |
| 323 | **worker_extra** (optional) |
| 324 | A dictionary of any extra metadata you may want to pass along. |
| 325 | |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 326 | It should then immediately send a WORK_STATUS packet with a value of 0 |
| 327 | percent complete. It may then optionally send subsequent WORK_STATUS |
| 328 | packets with updated completion values. |
| 329 | |
| 330 | When the build is complete, it should send a final WORK_DATA packet |
| 331 | with the following in JSON format: |
| 332 | |
| 333 | **result** |
| 334 | Either the string 'SUCCESS' if the job succeeded, or any other value |
| 335 | that describes the result if the job failed. |
| 336 | |
| 337 | Finally, it should send either a WORK_FAIL or WORK_COMPLETE packet as |
| 338 | appropriate. A WORK_EXCEPTION packet will be interpreted as a |
| 339 | WORK_FAIL, but the exception will be logged in Zuul's error log. |
| 340 | |
| 341 | Stopping Builds |
Joshua Hesketh | e898716 | 2014-03-13 13:05:33 +1100 | [diff] [blame] | 342 | ^^^^^^^^^^^^^^^ |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 343 | |
| 344 | If Zuul needs to abort a build already in progress, it will invoke the |
| 345 | following function through Gearman: |
| 346 | |
James E. Blair | 3c483cf | 2013-06-04 16:30:43 -0700 | [diff] [blame] | 347 | stop:MANAGER_NAME |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 348 | |
James E. Blair | 3c483cf | 2013-06-04 16:30:43 -0700 | [diff] [blame] | 349 | Where **MANAGER_NAME** is the name of the manager worker supplied in |
| 350 | the initial WORK_DATA packet when the job started. This is used to |
| 351 | direct the stop: function invocation to the correct Gearman worker |
| 352 | that is capable of stopping that particular job. The argument to the |
| 353 | function should be the following encoded in JSON format: |
| 354 | |
| 355 | **name** |
| 356 | The job name of the build to stop. |
| 357 | |
| 358 | **number** |
| 359 | The build number of the build to stop. |
James E. Blair | 1f4c2bb | 2013-04-26 08:40:46 -0700 | [diff] [blame] | 360 | |
| 361 | The original job is expected to complete with a WORK_DATA and |
| 362 | WORK_FAIL packet as described in `Starting Builds`_. |