4 The `Release Engineering Project <releng-wiki_>`_ consolidates the Jenkins jobs from
5 project-specific VMs to a single Jenkins server. Each OpenDaylight project
6 has a tab for their jobs on the `jenkins-master`_. The system utilizes
7 `Jenkins Job Builder <jjb-docs_>`_ for the creation and management of the
16 New Project Quick Start
17 -----------------------
21 We will be revamping releng/builder in the near future to simplify
24 This section attempts to provide details on how to get going as a new project
25 quickly with minimal steps. The rest of the guide should be read and understood
26 by those who need to create and contribute new job types that is not already
27 covered by the existing job templates provided by OpenDaylight's JJB repo.
29 As a new project you will be mainly interested in getting your jobs to appear
30 in the jenkins-master_ silo and this can be achieved by simply creating 2 files
31 project.cfg and project.yaml in the releng/builder project's jjb directory.
35 git clone https://git.opendaylight.org/gerrit/releng/builder
37 mkdir jjb/<new-project>
39 Where <new-project> should be the same name as your project's git repo in
40 Gerrit. So if your project is called "aaa" then create a new jjb/aaa directory.
42 Next we will create <new-project>.yaml as follows:
44 # REMOVE THIS LINE IF YOU WANT TO CUSTOMIZE ANYTHING BELOW
46 That's right all you need is the above comment in this file. Jenkins will
47 automatically regenerate this file when your patch is merged so we do not need
48 to do anything special here.
50 Next we will create <new-project>.cfg as follows:
58 DEPENDENCIES: odlparent,controller,yangtools
60 This is the minimal required CFG file contents and is used to auto-generate the
61 YAML file. If you'd like to explore the additional tweaking options available
62 please refer to the `Tuning Templates`_ section.
64 Finally we need to push these files to Gerrit for review by the releng/builder
65 team to push your jobs to Jenkins.
69 git add jjb/<new-project>
70 git commit -sm "Add <new-project> jobs to Jenkins"
73 This will push the jobs to Gerrit and your jobs will appear in Jenkins once the
74 releng/builder team has reviewed and merged your patch.
79 The `jenkins-master`_ is the home for all project's Jenkins jobs. All
80 maintenance and configuration of these jobs must be done via JJB through the
81 `releng-builder-repo`_. Project contributors can no longer edit the Jenkins jobs
82 directly on the server.
87 The Jenkins jobs are run on build minions (executors) which are created on an
88 as-needed basis. If no idle build minions are available a new VM is brought
89 up. This process can take up to 2 minutes. Once the build minion has finished a
90 job, it will remain online for 45 minutes before shutting down. Subsequent
91 jobs will use an idle build minion if available.
93 Our Jenkins master supports many types of dynamic build minions. If you are
94 creating custom jobs then you will need to have an idea of what type of minions
95 are available. The following are the current minion types and descriptions.
96 Minion Template Names are needed for jobs that take advantage of multiple
97 minions as they must be specifically called out by template name instead of
100 Adding New Components to the Minions
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
103 If your project needs something added to one of the minions used during build
104 and test you can help us get things added faster by doing one of the following:
106 * Submit a patch to RelEng/Builder for the `spinup-scripts`_ that
107 configures your new piece of software.
108 * Submit a patch to RelEng/Builder for the Vagrant template's bootstrap.sh in
109 the `vagrant-definitions`_ directory that configures your new piece of
112 Going the first route will be faster in the short term as we can inspect the
113 changes and make test modifications in the sandbox to verify that it works.
115 The second route, however, is better for the community as a whole as it will
116 allow others that utilize our Vagrant setups to replicate our systems more
117 closely. It is, however, more time consuming as an image snapshot needs to be
118 created based on the updated Vagrant definition before it can be attached to
119 the sandbox for validation testing.
121 In either case, the changes must be validated in the sandbox with tests to
122 make sure that we don't break current jobs and that the new software features
123 are operating as intended. Once this is done the changes will be merged and
124 the updates applied to the RelEng Jenkins production silo.
126 Please note that the combination of a Vagrant minion snapshot and a Jenkins
127 spinup script is what defines a given minion. For instance, a minion may be
128 defined by the `vagrant-basic-java-node`_ Vagrant definition
129 and the `spinup-scripts-controller.sh`_ Jenkins spinup script
130 (as the dynamic\_controller minion is). The pair provides the full definition of
131 the realized minion. Jenkins starts a minion using the last-spun Vagrant snapshot
132 for the specified definition. Once the base Vagrant instance is online Jenkins
133 checks out the RelEng/Builder repo on it and executes two scripts. The first is
134 `spinup-scripts-basic_settings.sh`_, which is a baseline for all of the minions.
136 the specialized spinup script, which handles any system updates, new software
137 installs or extra environment tweaks that don't make sense in a snapshot. After
138 all of these scripts have executed Jenkins will finally attach the minion as an
139 actual minion and start handling jobs on it.
146 <table class="table table-bordered">
148 <td><b>Jenkins Label</b><br/> dynamic_verify</td>
149 <td><b>Minion Template name</b><br/> centos7-builder</td>
150 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-builder</td>
151 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/builder.sh</td>
155 A CentOS 7 huild minion. This system has OpenJDK 1.7 (Java7) and OpenJDK
156 1.8 (Java8) installed on it along with all the other components and
157 libraries needed for building any current OpenDaylight project. This is
158 the label that is used for all basic -verify and -daily- builds for
164 <td><b>Jenkins Label</b><br/> dynamic_merge</td>
165 <td><b>Minion Template name</b><br/> centos7-builder</td>
166 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-builder</td>
167 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/builder.sh</td>
171 See dynamic_verify (same image on the back side). This is the label that
172 is used for all basic -merge and -integration- builds for projects.
177 <td><b>Jenkins Label</b><br/> matrix_master</td>
178 <td><b>Minion Template name</b><br/> centos7-matrix</td>
179 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
180 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/matrix.sh</td>
184 This is a very minimal system that is designed to spin up with 2 build
185 instances on it. The purpose is to have a location that is not the
186 Jenkins master itself for jobs that are executing matrix operations
187 since they need a director location. This image should not be used for
188 anything but tying matrix jobs before the matrx defined label ties.
193 <td><b>Jenkins Label</b><br/> dynamic_robot</td>
194 <td><b>Minion Template name</b><br/> centos7-robot</td>
195 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/integration-robotframework</td>
196 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/robot.sh</td>
200 A CentOS 7 minion that is configured with OpenJDK 1.7 (Java7), OpenJDK
201 1.8 (Java8) and all the current packages used by the integration
202 project for doing robot driven jobs. If you are executing robot
203 framework jobs then your job should be using this as the minion that
204 you are tied to. This image does not contain the needed libraries for
205 building components of OpenDaylight, only for executing robot tests.
210 <td><b>Jenkins Label</b><br/> ubuntu_mininet</td>
211 <td><b>Minion Template name</b><br/> ubuntu-trusty-mininet</td>
212 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ubuntu-mininet</td>
213 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/mininet-ubuntu.sh</td>
217 Basic Ubuntu system with ovs 2.0.2 and mininet 2.1.0
222 <td><b>Jenkins Label</b><br/> ubuntu_mininet_ovs_23</td>
223 <td><b>Minion Template name</b><br/> ubuntu-trusty-mininet-ovs-23</td>
224 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ubuntu-mininet-ovs-23</td>
225 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/mininet-ubuntu.sh</td>
229 Basic Ubuntu system with ovs 2.3 and mininet 2.2.1
234 <td><b>Jenkins Label</b><br/> dynamic_controller</td>
235 <td><b>Minion Template name</b><br/> centos7-java</td>
236 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
237 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
241 A CentOS 7 minion that has the basic OpenJDK 1.7 (Java7) and OpenJDK
242 1.8 (Java8) installed and is capable of running the controller, not
248 <td><b>Jenkins Label</b><br/> dynamic_java</td>
249 <td><b>Minion Template name</b><br/> centos7-java</td>
250 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
251 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
255 See dynamic_controller as it is currently the same image.
260 <td><b>Jenkins Label</b><br/> dynamic_java_8g</td>
261 <td><b>Minion Template name</b><br/> centos7-java-8g</td>
262 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/basic-java-node</td>
263 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/controller.sh</td>
267 See dynamic_controller as it is currently the same image but with 8G of RAM.
272 <td><b>Jenkins Label</b><br/> dynamic_devstack</td>
273 <td><b>Minion Template name</b><br/> centos7-devstack</td>
274 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ovsdb-devstack</td>
275 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/devstack.sh</td>
279 A CentOS 7 system purpose built for doing OpenStack testing using
280 DevStack. This minion is primarily targeted at the needs of the OVSDB
281 project. It has OpenJDK 1.7 (aka Java7) and OpenJDK 1.8 (Java8) and
282 other basic DevStack related bits installed.
287 <td><b>Jenkins Label</b><br/> dynamic_docker</td>
288 <td><b>Minion Template name</b><br/> centos7-docker</td>
289 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/ovsdb-docker</td>
290 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/docker.sh</td>
294 A CentOS 7 system that is configured with OpenJDK 1.7 (aka Java7),
295 OpenJDK 1.8 (Java8) and Docker. This system was originally custom
296 built for the test needs of the OVSDB project but other projects have
297 expressed interest in using it.
302 <td><b>Jenkins Label</b><br/> gbp_trusty</td>
303 <td><b>Minion Template name</b><br/> gbp_trusty</td>
304 <td><b>Vagrant Definition</b><br/> releng/builder/vagrant/gbp-ubuntu-docker-ovs-node</td>
305 <td><b>Spinup Script</b><br/> releng/builder/jenkins-scripts/ubuntu-docker-ovs.sh</td>
309 A basic Ubuntu node with latest OVS and docker installed. Used by Group Based Policy.
314 Creating Jenkins Jobs
315 ---------------------
317 Jenkins Job Builder takes simple descriptions of Jenkins jobs in YAML format
318 and uses them to configure Jenkins.
320 * `Jenkins Job Builder (JJB) documentation <jjb-docs_>`_
321 * `RelEng/Builder Gerrit <releng-builder-gerrit_>`_
322 * `RelEng/Builder Git repository <releng-builder-repo_>`_
324 Getting Jenkins Job Builder
325 ---------------------------
327 OpenDaylight uses Jenkins Job Builder to translate our in-repo YAML job
328 configuration into job descriptions suitable for consumption by Jenkins.
329 When testing new Jenkins Jobs in the `Jenkins Sandbox`_, you'll
330 need to use the `jenkins-jobs` executable to translate a set of jobs into
331 their XML descriptions and upload them to the sandbox Jenkins server.
333 We document `installing <Installing Jenkins Job Builder_>`_ `jenkins-jobs`
334 below. We also provide
335 a `pre-built Docker image <jjb-docker_>`_ with `jenkins-jobs` already installed.
337 Installing Jenkins Job Builder
338 ------------------------------
340 For users who aren't already experienced with Docker or otherwise don't want
341 to use our `pre-built JJB Docker image <jjb-docker_>`_, installing JJB into a
342 virtual environment is an equally good option.
344 We recommend using `pip <Installing JJB using pip_>`_ to assist with JJB
346 also document `installing from a git repository manually
347 <Installing JJB Manually_>`_.
348 For both, we recommend using Python `Virtual Environments`_
349 to isolate JJB and its dependencies.
351 The `builder/jjb/requirements.txt <odl-jjb-requirements.txt_>`_ file contains the currently
352 recommended JJB version. Because JJB is fairly unstable, it may be necessary
353 to debug things by installing different versions. This is documented for both
354 `pip-assisted <Installing JJB using pip_>`_ and `manual
355 <Installing JJB Manually_>`_ installs.
360 For both `pip-assisted <Installing JJB using pip_>`_ and `manual
361 <Installing JJB Manually_>`_ JJB
362 installs, we recommend using `Python Virtual Environments <python-virtualenv_>`_
363 to manage JJB and its
364 Python dependencies. The `python-virtualenvwrapper`_ tool can help you do so.
366 There are good docs for installing `python-virtualenvwrapper`_. On Linux systems
367 with pip (typical), they amount to:
371 sudo pip install virtualenvwrapper
373 A virtual environment is simply a directory that you install Python programs
374 into and then append to the front of your path, causing those copies to be
375 found before any system-wide versions.
377 Create a new virtual environment for JJB.
381 # Virtaulenvwrapper uses this dir for virtual environments
383 /home/daniel/.virtualenvs
384 # Make a new virtual environment
386 # A new venv dir was created
387 (jjb)$ ls -rc $WORKON_HOME | tail -n 1
389 # The new venv was added to the front of this shell's path
391 /home/daniel/.virtualenvs/jjb/bin:<my normal path>
392 # Software installed to venv, like pip, is found before system-wide copies
393 (jjb)$ command -v pip
394 /home/daniel/.virtualenvs/jjb/bin/pip
396 With your virtual environment active, you should install JJB. Your install will
397 be isolated to that virtual environment's directory and only visible when the
398 virtual environment is active.
400 You can easily leave and return to your venv. Make sure you activate it before
406 $ command -v jenkins-jobs
407 # No jenkins-jobs executable found
409 (jjb)$ command -v jenkins-jobs
410 $WORKON_HOME/jjb/bin/jenkins-jobs
412 Installing JJB using pip
413 ------------------------
415 The recommended way to install JJB is via pip.
417 First, clone the latest version of the `releng-builder-repo`_.
421 $ git clone https://git.opendaylight.org/gerrit/p/releng/builder.git
423 Before actually installing JJB and its dependencies, make sure you've `created
424 and activated <Virtual Environments_>`_ a virtual environment for JJB.
430 The recommended version of JJB to install is the version specified in the
431 `builder/jjb/requirements.txt <odl-jjb-requirements.txt_>`_ file.
435 # From the root of the releng/builder repo
436 (jjb)$ pip install -r jjb/requirements.txt
438 To validate that JJB was successfully installed you can run this command:
442 (jjb)$ jenkins-jobs --version
444 To change the version of JJB specified by `builder/jjb/requirements.txt
445 <odl-jjb-requirements.txt_>`_
446 to install from the latest commit to the master branch of JJB's git repository:
450 $ cat jjb/requirements.txt
451 -e git+https://git.openstack.org/openstack-infra/jenkins-job-builder#egg=jenkins-job-builder
453 To install from a tag, like 1.4.0:
457 $ cat jjb/requirements.txt
458 -e git+https://git.openstack.org/openstack-infra/jenkins-job-builder@1.4.0#egg=jenkins-job-builder
460 Installing JJB Manually
461 -----------------------
463 This section documents installing JJB from its manually cloned repository.
465 Note that `installing via pip <Installing JJB using pip_>`_ is typically simpler.
467 Checkout the version of JJB's source you'd like to build.
469 For example, using master:
473 $ git clone https://git.openstack.org/openstack-infra/jenkins-job-builder
475 Using a tag, like 1.4.0:
479 $ git clone https://git.openstack.org/openstack-infra/jenkins-job-builder
480 $ cd jenkins-job-builder
481 $ git checkout tags/1.4.0
483 Before actually installing JJB and its dependencies, make sure you've `created
484 and activated <Virtual Environments_>`_ a virtual environment for JJB.
490 You can then use JJB's `requirements.txt <jjb-requirements.txt_>`_ file to
492 dependencies. Note that we're not using `sudo` to install as root, since we want
493 to make use of the venv we've configured for our current user.
497 # In the cloned JJB repo, with the desired version of the code checked out
498 (jjb)$ pip install -r requirements.txt
500 Then install JJB from the repo with:
506 To validate that JJB was successfully installed you can run this command:
510 (jjb)$ jenkins-jobs --version
515 `Docker <docker-docs_>`_ is an open platform used to create virtualized Linux containers
516 for shipping self-contained applications. Docker leverages LinuX Containers
517 \(LXC\) running on the same operating system as the host machine, whereas a
518 traditional VM runs an operating system over the host.
522 docker pull zxiiro/jjb-docker
523 docker run --rm -v ${PWD}:/jjb jjb-docker
525 This `Dockerfile <jjb-dockerfile_>`_ created the
526 `zxiiro/jjb-docker image <jjb-docker_>`_.
527 By default it will run:
533 You'll need to use the `-v/--volume=[]` parameter to mount a directory
534 containing your YAML files, as well as a configured `jenkins.ini` file if you
535 wish to upload your jobs to the `Jenkins Sandbox`_.
537 Jenkins Job Templates
538 ---------------------
540 The OpenDaylight `RelEng/Builder <releng-builder-wiki_>`_ project provides
541 `jjb-templates`_ that can be used to define basic jobs.
543 The *Gerrit Trigger* listed in the jobs are keywords that can be used to
544 trigger the job to run manually by simply leaving a comment in Gerrit for the
545 patch you wish to trigger against.
549 <table class="table table-bordered">
551 <td><b>Job Template</b><br/>{project}-distribution-{stream}</td>
552 <td><b>Gerrit Trigger</b><br/>test-distribution</td>
556 This job builds a distrbution against your patch, passes distribution sanity test
557 and reports back the results to Gerrit. Leave a comment with trigger keyword above
558 to activate it for a particular patch.
560 This job is maintained by the <a href="https://wiki.opendaylight.org/view/Integration/Test">Integration/Test</a>
563 <div class="admonition note">
564 <p class="first admonition-title">Note</p>
566 Running the "test-distribution" trigger will cause Jenkins to
567 remove it's existing vote if it's already -1 or +1'd a comment.
568 You will need to re-run your verify job (recheck) after running
569 this to get Jenkins to put back the correct vote.
576 <td><b>Job Template</b><br/>{project}-integration-{stream}</td>
581 The Integration Job Template creates a job which runs when a project that your
582 project depends on is successfully built. This job type is basically the same
583 as a verify job except that it triggers from other Jenkins jobs instead of via
584 Gerrit review updates. The dependencies that triger integration jobs are listed
585 in your project.cfg file under the <b>DEPENDENCIES</b> variable.
587 If no dependencies are listed then this job type is disabled by default.
592 <td><b>Job Template</b><br/>{project}-merge-{stream}</td>
593 <td><b>Gerrit Trigger</b><br/>remerge</td>
597 The Merge job template is similar to the Verify Job Template except
598 it will trigger once a Gerrit patch is merged into the repo. It
599 also automatically runs the Maven goals <b>source:jar</b> and
602 This job will upload artifacts to OpenDaylight's
603 <a href="https://nexus.opendaylight.org">Nexus</a> on completion.
608 <td><b>Job Template</b><br/>{project}-sonar</td>
609 <td><b>Gerrit Trigger</b><br/>run-sonar</td>
613 This job runs Sonar analysis and reports the results to
614 OpenDaylight's <a href="https://sonar.opendaylight.org">Sonar</a>
617 The Sonar Job Template creates a job which will run against the
618 master branch, or if BRANCHES are specified in the CFG file it will
619 create a job for the <b>First</b> branch listed.
621 <div class="admonition note">
622 <p class="first admonition-title">Note</p>
624 Running the "run-sonar" trigger will cause Jenkins to remove
625 its existing vote if it's already -1'd or +1'd a comment. You
626 will need to re-run your verify job (recheck) after running
627 this to get Jenkins to re-vote.
634 <td><b>Job Template</b><br/>{project}-validate-autorelease-{stream}</td>
635 <td><b>Gerrit Trigger</b><br/>recheck | reverify</td>
639 This job runs the PROJECT-validate-autorelease-BRANCH job which is
640 used as a quick sanity test to ensure that a patch does not depend on
641 features that do not exist in the current release.
643 The <b>revalidate</b> trigger is useful in cases where a project's
644 verify job passed however validate failed due to infra problems or
645 intermittent issues. It will retrigger just the validate-autorelease
651 <td><b>Job Template</b><br/>{project}-verify-{stream}</td>
652 <td><b>Gerrit Trigger</b><br/>recheck | reverify</td>
656 The Verify job template creates a Gerrit Trigger job that will
657 trigger when a new patch is submitted to Gerrit.
662 <td><b>Job Template</b><br/>{project}-verify-node-{stream}</td>
663 <td><b>Gerrit Trigger</b><br/>recheck | reverify</td>
667 This job template can be used by a project that is NodeJS based. It
668 simply installs a python virtualenv and uses that to install nodeenv
669 which is then used to install another virtualenv for nodejs. It then
670 calls <b>npm install</b> and <b>npm test</b> to run the unit tests.
671 When using this template you need to provide a {nodedir} and
672 {nodever} containing the directory relative to the project root
673 containing the nodejs package.json and version of node you wish to
679 <td><b>Job Template</b><br/>{project}-verify-python-{stream}</td>
680 <td><b>Gerrit Trigger</b><br/>recheck | reverify</td>
684 This job template can be used by a project that is Python based. It
685 simply installs a python virtualenv and uses tox to run tests. When
686 using the template you need to provide a {toxdir} which is the path
687 relative to the root of the project repo containing the tox.ini file.
692 <td><b>Job Template</b><br/>integration-patch-test-{stream}</td>
693 <td><b>Gerrit Trigger</b><br/>test-integration</td>
697 This job runs a full integration test suite against your patch and
698 reports back the results to Gerrit. Leave a comment with trigger
699 keyword above to activate it for a particular patch.
701 It then spawns the list of jobs in csit-list defined
702 <a href="https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jjb/integration/integration-test-jobs.yaml">here</a>.
704 This job is maintained by the <a href="https://wiki.opendaylight.org/view/Integration/Test">Integration/Test</a>
707 <div class="admonition note">
708 <p class="first admonition-title">Note</p>
710 Running the "test-integration" trigger will cause Jenkins to remove
711 it's existing vote if it's already -1 or +1'd a comment. You will need
712 to re-run your verify job (recheck) after running this to get Jenkins
713 to put back the correct vote.
717 Some considerations when using this job:
720 The patch test verification takes some time (~2 hours) + consumes a lot of
721 resources so it is not meant to be used for every patch.
724 The system tests for master patches will fail most of the times because both
725 code and test are unstable during the release cycle (should be good by the
729 Because of the above, patch test results typically have to be interpreted by
730 system test experts. The <a href="https://wiki.opendaylight.org/view/Integration/Test">Integration/Test</a>
731 project can help with that.
737 Basic Job Configuration
738 -----------------------
740 To create jobs based on existing `templates <Jenkins Job Templates_>`_, use the
741 `jjb-init-project.py`_ helper script. When run from the root of
742 `RelEng/Builder's repo <releng-builder-repo_>`_, it will produce a file in
743 `jjb/<project>/<project>.yaml` containing your project's base template.
747 $ python scripts/jjb-init-project.py --help
748 usage: jjb-init-project.py [-h] [-c CONF] [-d DEPENDENCIES] [-t TEMPLATES]
749 [-s STREAMS] [-p POM] [-g MVN_GOALS] [-o MVN_OPTS]
750 [-a ARCHIVE_ARTIFACTS]
753 positional arguments:
757 -h, --help show this help message and exit
758 -c CONF, --conf CONF Config file
759 -d DEPENDENCIES, --dependencies DEPENDENCIES
760 Project dependencies A comma-seperated (no spaces)
761 list of projects your project depends on. This is used
762 to create an integration job that will trigger when a
763 dependent project-merge job is built successfully.
764 Example: aaa,controller,yangtools
765 -t TEMPLATES, --templates TEMPLATES
767 -s STREAMS, --streams STREAMS
768 Release streams to fill with default options
769 -p POM, --pom POM Path to pom.xml to use in Maven build (Default:
771 -g MVN_GOALS, --mvn-goals MVN_GOALS
773 -o MVN_OPTS, --mvn-opts MVN_OPTS
775 -a ARCHIVE_ARTIFACTS, --archive-artifacts ARCHIVE_ARTIFACTS
776 Comma-seperated list of patterns of artifacts to
777 archive on build completion. See:
778 http://ant.apache.org/manual/Types/fileset.html
780 If all your project requires is the basic verify, merge, and daily jobs then
781 using the job template should be all you need to configure for your jobs.
783 Auto-Update Job Templates
784 ^^^^^^^^^^^^^^^^^^^^^^^^^
786 The first line of the job YAML file produced by the `jjb-init-project.py`_ script will
787 contain the words `# REMOVE THIS LINE IF...`. Leaving this line will allow the
788 RelEng/Builder `jjb-autoupdate-project.py`_ script to maintain this file for your project,
789 should the base templates ever change. It is a good idea to leave this line if
790 you do not plan to create any complex jobs outside of the provided template.
792 However, if your project needs more control over your jobs or if you have any
793 additional configuration outside of the standard configuration provided by the
794 template, then this line should be removed.
799 Allowing the auto-updated to manage your templates doesn't prevent you from
800 doing some configuration changes. Parameters can be passed to templates via
801 a `<project>.cfg` in your `builder/jjb/<project>` directory. An example is
802 provided below, others can be found in the repos of other projects. Tune as
803 necessary. Unnecessary paramaters can be removed or commented out with a "#"
808 JOB_TEMPLATES: verify,merge,sonar
812 jdks: openjdk7,openjdk8
815 branch: stable/lithium
818 MVN_GOALS: clean install javadoc:aggregate -DrepoBuild -Dmaven.repo.local=$WORKSPACE/.m2repo -Dorg.ops4j.pax.url.mvn.localRepository=$WORKSPACE/.m2repo
819 MVN_OPTS: -Xmx1024m -XX:MaxPermSize=256m
820 DEPENDENCIES: aaa,controller,yangtools
821 ARCHIVE_ARTIFACTS: *.logs, *.patches
823 .. note:: `STREAMS <streams-design-background_>`_ is a list of branches you want
824 JJB to generate jobs for.
825 The first branch will be the branch that reports Sonar analysis. Each
826 branch must define a "jdks:" section listing the JDKs the verify jobs
827 should run tests against for the branch. The first JDK listed will be
828 used as the default JDK for non-verify type jobs.
830 .. note:: Projects that are participating in the simultanious release should set
831 "autorelease: true" under the streams they are participating in
832 autorelease for. This enables a new job type validate-autorelease
833 which is used to help identify if Gerrit patches might break
839 It is also possible to take advantage of both the auto-updater and creating
840 your own jobs. To do this, create a YAML file in your project's sub-directory
841 with any name other than \<project\>.yaml. The auto-update script will only
842 search for files with the name \<project\>.yaml. The normal \<project\>.yaml
843 file can then be left in tact with the "# REMOVE THIS LINE IF..." comment so
844 it will be automatically updated.
849 We provide a properties which your job can take advantage of if you want to do
850 something different depending on the job type that is run. If you create a
851 profile that activates on a property listed blow. The JJB templated jobs will
852 be able to activate the profile during the build to run any custom code you
853 wish to run in your project.
857 -Dmerge : This flag is passed in our Merge job and is equivalent to the
860 -Dsonar : This flag is passed in our Sonar job and is equivalent to the
867 The `jenkins-sandbox`_ instance's purpose is to allow projects to test their JJB
868 setups before merging their code over to the RelEng master silo. It is
869 configured similarly to the master instance, although it cannot publish
870 artifacts or vote in Gerrit.
872 If your project requires access to the sandbox please open an OpenDaylight
873 Helpdesk ticket (<helpdesk@opendaylight.org>) and provide your ODL ID.
875 Notes Regarding the Sandbox
876 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
878 * Jobs are automatically deleted every Saturday at 08:00 UTC
879 * Committers can login and configure Jenkins jobs in the sandbox directly
880 (unlike with the master silo)
881 * Sandbox configuration mirrors the master silo when possible
882 * Sandbox jobs can NOT upload artifacts to Nexus
883 * Sandbox jobs can NOT vote on Gerrit
888 Make sure you have Jenkins Job Builder [properly installed](#jjb_install).
890 If you do not already have access, open an OpenDaylight Helpdesk ticket
891 (<helpdesk@opendaylight.org>) to request access to ODL's sandbox instance.
892 Integration/Test (`integration-test-wiki`_) committers have access by default.
894 JJB reads user-specific configuration from a `jenkins.ini`_. An
895 example is provided by releng/builder at `example-jenkins.ini`_.
899 # If you don't have RelEng/Builder's repo, clone it
900 $ git clone https://git.opendaylight.org/gerrit/p/releng/builder.git
901 # Make a copy of the example JJB config file (in the builder/ directory)
902 $ cp jenkins.ini.example jenkins.ini
903 # Edit jenkins.ini with your username, API token and ODL's sandbox URL
907 user=<your ODL username>
908 password=<your ODL Jenkins sandbox API token>
909 url=https://jenkins.opendaylight.org/sandbox
912 To get your API token, `login to the Jenkins **sandbox** instance
913 <jenkins-sandbox-login_>`_ (*not
914 the main master Jenkins instance, different tokens*), go to your user page (by
915 clicking on your username, for example), click "Configure" and then "Show API
921 If you `installed JJB locally into a virtual environment
922 <Installing Jenkins Job Builder_>`_,
923 you should now activate that virtual environment to access the `jenkins-jobs`
931 You'll want to work from the root of the RelEng/Builder repo, and you should
932 have your `jenkins.ini` file [properly configured](#sandbox_config).
937 It's good practice to use the `test` command to validate your JJB files before
942 jenkins-jobs --conf jenkins.ini test jjb/ <job-name>
944 If the job you'd like to test is a template with variables in its name, it
945 must be manually expanded before use. For example, the commonly used template
946 `{project}-csit-verify-1node-{functionality}` might expand to
947 `ovsdb-csit-verify-1node-netvirt`.
951 jenkins-jobs --conf jenkins.ini test jjb/ ovsdb-csit-verify-1node-netvirt
953 Successful tests output the XML description of the Jenkins job described by
954 the specified JJB job name.
959 Once you've `configured your \`jenkins.ini\` <Configuration_>`_ and `verified your
960 JJB jobs <Testing Jobs_>`_ produce valid XML descriptions of Jenkins jobs you
961 can push them to the Jenkins sandbox.
965 When pushing with `jenkins-jobs`, a log message with the number
966 of jobs you're pushing will be issued, typically to stdout.
967 **If the number is greater than 1** (or the number of jobs you
968 passed to the command to push) then you are pushing too many
969 jobs and should **`ctrl+c` to cancel the upload**. Else you will
970 flood the system with jobs.
974 INFO:jenkins_jobs.builder:Number of jobs generated: 1
976 **Failing to provide the final `<job-name>` param will push all
981 # Don't push all jobs by omitting the final param! (ctrl+c to abort)
982 jenkins-jobs --conf jenkins.ini update jjb/ <job-name>
987 Once you have your Jenkins job configuration `pushed to the
988 Sandbox <Pushing Jobs_>`_ you can trigger it to run.
990 Find your newly-pushed job on the `Sandbox's web UI <jenkins-sandbox_>`_. Click
991 on its name to see the job's details.
993 Make sure you're `logged in <jenkins-sandbox-login_>`_ to the Sandbox.
995 Click "Build with Parameters" and then "Build".
997 Wait for your job to be scheduled and run. Click on the job number to see
998 details, including console output.
1000 Make changes to your JJB configuration, re-test, re-push and re-run until
1006 If `using Docker <JJB Docker image_>`_:
1008 .. code-block:: bash
1011 docker run --rm -v ${PWD}:/jjb zxiiro/jjb-docker
1015 When pushing with `jenkins-jobs`, a log message with
1016 the number of jobs you're pushing will be issued, typically to stdout.
1017 **If the number is greater than 1** (or the number of jobs you passed to
1018 the command to push) then you are pushing too many jobs and should **`ctrl+c`
1019 to cancel the upload**. Else you will flood the system with jobs.
1021 .. code-block:: bash
1023 INFO:jenkins_jobs.builder:Number of jobs generated: 1
1025 **Failing to provide the final `<job-name>` param will push all jobs!**
1027 .. code-block:: bash
1029 # To upload jobs to the sandbox
1030 # Please ensure that you include a configured jenkins.ini in your volume mount
1031 # Making sure not to push more jobs than expected, ctrl+c to abort
1032 docker run --rm -v ${PWD}:/jjb zxiiro/jjb-docker jenkins-jobs --conf jenkins.ini update . openflowplugin-csit-periodic-1node-cds-longevity-only-master
1034 .. _docker-docs: https://www.docker.com/whatisdocker/
1035 .. _example-jenkins.ini: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins.ini.example
1036 .. _integration-test-wiki: https://wiki.opendaylight.org/view/Integration/Test
1037 .. _jenkins-master: https://jenkins.opendaylight.org/releng
1038 .. _jenkins-sandbox: https://jenkins.opendaylight.org/sandbox
1039 .. _jenkins-sandbox-login: https://jenkins.opendaylight.org/sandbox/login
1040 .. _jenkins.ini: http://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file
1041 .. _jjb-autoupdate-project.py: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=scripts/jjb-autoupdate-project.py
1042 .. _jjb-docker: https://hub.docker.com/r/zxiiro/jjb-docker/
1043 .. _jjb-dockerfile: https://github.com/zxiiro/jjb-docker/blob/master/Dockerfile
1044 .. _jjb-docs: http://ci.openstack.org/jenkins-job-builder/
1045 .. _jjb-init-project.py: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=scripts/jjb-init-project.py
1046 .. _jjb-repo: https://github.com/openstack-infra/jenkins-job-builder
1047 .. _jjb-requirements.txt: https://github.com/openstack-infra/jenkins-job-builder/blob/master/requirements.txt
1048 .. _jjb-templates: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=jjb
1049 .. _odl-jjb-requirements.txt: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jjb/requirements.txt
1050 .. _odl-nexus: https://nexus.opendaylight.org
1051 .. _odl-sonar: https://sonar.opendaylight.org
1052 .. _python-virtualenv: https://virtualenv.readthedocs.org/en/latest/
1053 .. _python-virtualenvwrapper: https://virtualenvwrapper.readthedocs.org/en/latest/
1054 .. _releng-wiki: https://wiki.opendaylight.org/view/RelEng:Main
1055 .. _releng-builder-gerrit: https://git.opendaylight.org/gerrit/#/admin/projects/releng/builder
1056 .. _releng-builder-repo: https://git.opendaylight.org/gerrit/gitweb?p=releng%2Fbuilder.git;a=summary
1057 .. _releng-builder-wiki: https://wiki.opendaylight.org/view/RelEng/Builder
1058 .. _streams-design-background: https://lists.opendaylight.org/pipermail/release/2015-July/003139.html
1059 .. _spinup-scripts: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=jenkins-scripts
1060 .. _spinup-scripts-basic_settings.sh: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins-scripts/basic_settings.sh
1061 .. _spinup-scripts-controller.sh: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins-scripts/controller.sh
1062 .. _vagrant-basic-java-node: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=vagrant/basic-java-node
1063 .. _vagrant-definitions: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=tree;f=vagrant