docs/octopus_docs/opnfv-jjb-usage.rst

   1 How to write and use JJB?
   2 ============================================
   3
   4 What is Jenkins Job Builder
   5 ----------------------------
   6
   7 Jenkins Job Builder(JJB) takes simple descriptions of Jenkins jobs in YAML format,
   8 and uses them to configure Jenkins jobs.
   9 JJB keeps your job descriptions in human readable format and job template system
  10 simplifies the configuration of Jenkins jobs.
  11 Upstream documentation is available at http://ci.openstack.org/jenkins-job-builder/.
  12
  13 How to Write/Use Jenkins Job Builder
  14 ------------------------------------
  15
  16 Job template is widely used in JJBs and makes the configuration of Jenkins jobs simple,
  17 if you need to define several jobs which are nearly identical, except perhaps in their names, SCP targets, etc.,
  18 then you may use a job template to specify the particulars of the job,
  19 and then use a project to realize the job with appropriate variable substitution.
  20
  21 To illustrate how to configure Jenkins jobs by using job template,
  22 we can start with a simple example used in our OPNFV releng project octopus directory,
  23 which is just used to print "Hello world from Octopus", shown as below::
  24
  25  -job-template:
  26     name: octopus-test
  27
  28     node: master
  29
  30     project-type: freestyle
  31
  32     logrotate:
  33         daysToKeep: 30
  34         numToKeep: 10
  35         artifactDaysToKeep: -1
  36         artifactNumToKeep: -1
  37
  38     builders:
  39         - shell: |
  40             echo "Hello world from octopus"
  41
  42 the value "-1" here means keep forever, you can add this job template into the project jobs to run in jenkins::
  43
  44  - project:
  45      name: octopus
  46      jobs:
  47          - 'octopus-test'
  48
  49 then this job works!
  50
  51 Further, if you are a developer who wants to set up a job template to be used in jenkins,
  52 we should dive into much more, taking one job template in releng project used for octopus project,
  53 the 'octopus-daily-{stream}', as an example::
  54
  55  -job-template:
  56     name: 'octopus-daily-{stream}'
  57
  58     node: master
  59
  60     # Job template for daily builders
  61     #
  62     # Required Variables:
  63     #     stream:    branch with - in place of / (eg. stable)
  64     #     branch:    branch (eg. stable)
  65
  66     project-type: freestyle
  67     varsetabove: '{somevar}'
  68
  69     logrotate:
  70         daysToKeep: '{build-days-to-keep}'
  71         numToKeep: '{build-num-to-keep}'
  72         artifactDaysToKeep: '{build-artifact-days-to-keep}'
  73         artifactNumToKeep: '{build-artifact-num-to-keep}'
  74
  75     parameters:
  76         - project-parameter:
  77             project: '{project}'
  78
  79     scm:
  80         - git-scm:
  81             credentials-id: '{ssh-credentials}'
  82             refspec: ''
  83             branch: '{branch}'
  84
  85     wrappers:
  86         - ssh-agent-credentials:
  87             user: '{ssh-credentials}'
  88
  89     triggers:
  90         - timed: 'H H * * *'
  91
  92     prebuilders:
  93         - test-macro
  94
  95     builders:
  96         - shell:
  97             !include-raw build-upload-docu.sh
  98
  99     postbulders:
 100         - test-macro
 101
 102 the {stream} here means when you add this into jobs, you can replace {stream} with what you want, such as::
 103
 104  stream:
 105         - master:
 106             branch: 'master'
 107
 108 the::
 109
 110  node: master
 111
 112 means to restrict this job to run in Jenkins master node. Next, several important procedures are illustrated here,
 113
 114 - scm, this mudule allows you to specify the source code location for the project,
 115 and it allows referencing multiple repositories in a Jenkins job.
 116 - triggers, this module defines what causes a Jenkins job to start building.
 117 - prebuilders and postbuilders, which define job need done pre and post the builders.
 118 - builders, which defines actions that the Jenkins job should execute,
 119 usually the shell scripts or maven targets are existed there, e.g., build-upload-docu.sh used in our example.
 120
 121 Generally, the modules used in a job template is sequenced as
 122
 123 1. parameters, properties
 124 2. scm
 125 3. triggers
 126 4. wrappers
 127 5. prebuilders
 128 6. builders
 129 7. postbuilders
 130 8. publishers, reporters, notifications
 131
 132 Working with OPNFV Jenkins Jobs
 133 -------------------------------
 134
 135 By now, the releng project of OPNFV is the release engineering project for JJBs, you can clone the repo::
 136
 137  git clone ssh://YOU@gerrit.opnfv.org:29418/releng
 138
 139 make changes::
 140
 141  git commit -sv
 142  git review
 143  remote: Resolving deltas: 100% (3/3)
 144  remote: Processing changes: new: 1, refs: 1, done
 145  remote:
 146  remote: New Changes:
 147  remote:   https://gerrit.opnfv.org/gerrit/51
 148  remote:
 149  To ssh://agardner@gerrit.opnfv.org:29418/releng.git
 150   "* [new branch]      HEAD -> refs/publish/master
 151
 152 Follow the link to gerrit https://gerrit.opnfv.org/gerrit/51 in a few moments
 153 the verify job will have completed and you will see Verified +1 jenkins-ci in the gerrit ui.
 154
 155 If the changes pass the verify job https://build.opnfv.org/ci/view/builder/job/builder-verify-jjb/ The patch can be submitted by a committer.
 156
 157 The verify and merge jobs are retriggerable in Gerrit by simply leaving a comment with one of the keywords listed below.
 158 This is useful in case you need to re-run one of those jobs in case if build issues or
 159 something changed with the environment.
 160
 161 * Verify Job: Trigger: **recheck** or **reverify**
 162
 163 * Merge Job: Trigger: **remerge**
 164
 165 You can add below persons as reviewers to your patch in order to get it reviewed and submitted.
 166
 167 * Ulrich Kleber (Ulrich.Kleber@huawei.com)
 168 * Fatih Degirmenci (fatih.degirmenci@ericsson.com)
 169 * Xinyu Zhao(Jerry) (zhaoxinyu@huawei.com)
 170 * Aric Gardner (agardner@linuxfoundation.org)
 171
 172 The Current merge and verify jobs for jenkins job builder for releng project, shown in https://git.opnfv.org/cgit/releng/tree/jjb.
 173
 174 Assuming that you have set up some job templates and put them into a project,
 175 then the question is that how they work? Taking the jobs 'builder-verify-jjb',
 176 'builder-merge' used in releng project as examples, 'builder-verify-jjb' is to verify jobs you commited,
 177 you will see verified '+1' jenkins-ci in gerrit if it succeed,
 178 'builder-merge' is to set up a merge job and update all the JJBs.
 179 If you have some new jobs need to be run, you can set up your own job templates and add them into the project.