From e0f5bb4abd0076697b88c0e64acb1277bf955690 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Tue, 4 Mar 2014 11:30:37 +0100 Subject: [PATCH] Document the Zuul triggers Zuul send different sets of parameters depending on the event that triggered a build, split the parameters in sub sub sections for some clarity. Added examples of ref-updated parameters. Sub-sub section for the jenkins configuration. Change-Id: I1edcd5c3a101e2afe0025ad4cd3e511582998999 --- doc/source/launchers.rst | 46 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/doc/source/launchers.rst b/doc/source/launchers.rst index db499333e7..9e27f87213 100644 --- a/doc/source/launchers.rst +++ b/doc/source/launchers.rst @@ -73,8 +73,13 @@ Zuul Parameters Zuul will pass some parameters with every job it launches. The Gearman Plugin will ensure these are supplied as Jenkins build parameters, so they will be available for use in the job configuration -as well as to the running job as environment variables. They are as -follows: +as well as to the running job as environment variables. Builds can +be triggered either by an action on a change or by a reference update. +Both events share a common set of parameters and more specific +parameters as follows: + +Common parameters +~~~~~~~~~~~~~~~~~ **ZUUL_UUID** Zuul provided key to link builds with Gerrit events @@ -91,6 +96,9 @@ follows: A test runner may use this URL as the basis for fetching git commits. +Change related parameters +~~~~~~~~~~~~~~~~~~~~~~~~~ + The following additional parameters will only be provided for builds associated with changes (i.e., in response to patchset-created or comment-added events): @@ -105,6 +113,9 @@ comment-added events): **ZUUL_PATCHSET** The Gerrit patchset number for the change that triggered this build +Reference updated parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The following additional parameters will only be provided for post-merge (ref-updated) builds: @@ -119,6 +130,37 @@ post-merge (ref-updated) builds: **ZUUL_SHORT_NEWREV** The shortened (7 character) SHA1 of the new revision +Unset revisions default to 00000000000000000000000000000000. + +Examples: + +When a reference is created:: + + ZUUL_OLDREV=00000000000000000000000000000000 + ZUUL_NEWREV=123456789abcdef123456789abcdef12 + ZUUL_SHORT_OLDREV=0000000 + ZUUL_SHORT_NEWREV=1234567 + +When a reference is deleted:: + + ZUUL_OLDREV=123456789abcdef123456789abcdef12 + ZUUL_NEWREV=00000000000000000000000000000000 + ZUUL_SHORT_OLDREV=1234567 + ZUUL_SHORT_NEWREV=0000000 + +And finally a reference being altered:: + + ZUUL_OLDREV=123456789abcdef123456789abcdef12 + ZUUL_NEWREV=abcdef123456789abcdef123456789ab + ZUUL_SHORT_OLDREV=1234567 + ZUUL_SHORT_NEWREV=abcdef1 + +Your jobs can check whether the parameters are ``000000`` to act +differently on each kind of event. + +Jenkins git plugin configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + In order to test the correct build, configure the Jenkins Git SCM plugin as follows::