From aaeb5e3230b00d7aafc4cad463d55f8fdca11ad0 Mon Sep 17 00:00:00 2001 From: Ramy Asselin Date: Wed, 21 Jan 2015 12:17:34 -0800 Subject: [PATCH] Add Zuul Gerrit Trigger Way & JJB Updated the third party ci using a few sections of Jay Pipe's blog as a reference, and in some cases copy-paste. http://www.joinfu.com/2014/01/understanding-the-openstack-ci-system/ Change-Id: I6c70bedeca890041b8d1acf700958f25686b8fd4 --- doc/source/third_party.rst | 87 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/doc/source/third_party.rst b/doc/source/third_party.rst index f697be1302..d5dfa7559f 100644 --- a/doc/source/third_party.rst +++ b/doc/source/third_party.rst @@ -260,6 +260,93 @@ should configure as follows:: This job will now automatically trigger when a new patchset is uploaded and will report the results to Gerrit automatically. +The Zuul Gerrit Trigger Way +--------------------------- + +`Zuul `_ is a tool that determines what jobs are run when. +Zuul listens to the Gerrit event stream, and first tries to match each event to one or more pipelines. +Zuul’s pipelines are configured in a single file called layout.yaml. +Here’s a snippet from that file that constructs the ``check`` pipeline taken from this +`Zuul sample layout.yaml file `_ + +.. code-block:: yaml + + pipelines: + - name: check + manager: IndependentPipelineManager + trigger: + gerrit: + - event: patchset-created + success: + gerrit: + verified: 1 + failure: + gerrit: + verified: -1 + + +This pipeline is configured to trigger on any Gerrit event that represents a new +patch set created. The matching event will invoke the configured Jenkins job(s) +(discussed next). If all the Jenkins jobs are successful, Zuul will add a comment +to Gerrit with a ``verified +1`` vote, and if any one fails, with a ``verified -1``. + +The sample includes other possible configurations, or you can configure your own by +following the `Zuul layout documentation `_ + +After a Gerrit event matches a pipeline, Zuul will look at the project identified +in that Gerrit event and invoke the Jenkins jobs specified in the ``projects`` section +(for the matching pipeline) using the `Jenkins Gearman Plugin +`_. + +For example: + +.. code-block:: yaml + + projects: + - name: openstack-dev/ci-sandbox + check: + - my-sandbox-check + test: + - my-sandbox-test + + +In this case, any Gerrit event generated from the ``openstack-dev/ci-sandbox`` project, that matched +the ``check`` pipeline would run the ``my-sandbox-check`` job in Jenkins. If the +Gerrit event also matched the ``test`` pipeline, Zuul would also invoke the ``my-sandbox-test`` +Jenkins job. + +The `layout.yaml `_ +used by OpenStack is a good reference for real world pipeline definitions, +and project-pipeline-job definitions. + +Managing Jenkins Jobs +--------------------- +When code is pushed to Gerrit, a series of jobs are triggered that run a series +of tests against the proposed code. `Jenkins `_ +is the server that executes and +manages these jobs. It is a Java application with an extensible architecture +that supports plugins that add functionality to the base server. + +Each job in Jenkins is configured separately. Behind the scenes, Jenkins stores +this configuration information in an XML file in its data directory. +You may manually edit a Jenkins job as an administrator in Jenkins. However, +in a testing platform as large as the upstream OpenStack CI system, +doing so manually would be virtually impossible and fraught with errors. +Luckily, there is a helper tool called `Jenkins Job Builder (JJB) +`_ that +constructs and manages these XML configuration files after reading a +set of YAML files and job templating rules. These references provide more details: + +* `A basic overview of using JJB to define projects, templates, and jobs in yaml + format is available here. `_ + +* `The official documentation to define Jenkins jobs using JJB is here. + `_ + +* `The JJB description of all jobs used by OpenStack are defined in this folder. + `_ + (The projects.yaml file is a good starting point) + Testing your CI setup ---------------------