README.md

   1 # Global JJB
   2
   3 The purpose of this repository is store generically defined, reusable JJB
   4 templates, deployable across LF projects.
   5
   6 Define the following variables in the Jenkins server as
   7 global environment variables as scripts in this repo expect these variables to
   8 be available.
   9
  10 For example:
  11
  12 ```
  13 GIT_URL=ssh://jenkins-$SILO@git.opendaylight.org:29418
  14 GIT_CLONE_URL=git@github.com:
  15 JENKINS_HOSTNAME=jenkins092
  16 LOGS_SERVER=https://logs.opendaylight.org
  17 NEXUS_URL=https://nexus.opendaylight.org
  18 SILO=releng
  19 ```
  20
  21 Note: Use **GIT_CLONE_URL** for GitHub projects as this
  22 will be different from the URL used the poperties
  23 configuration.
  24
  25 ## Jenkins Plugin Requirements
  26
  27 **Required**
  28
  29 - Config File Provider
  30 - Description Setter
  31 - Gerrit Trigger
  32 - Post Build Script
  33 - SSH Agent
  34 - Workspace Cleanup
  35
  36 **Optional**
  37
  38 - Mask Passwords
  39 - MsgInject
  40 - OpenStack Cloud
  41 - Timestamps
  42
  43 ## Installing global-jjb
  44
  45 Deploy global-jjb in the ci-management repository's jjb directory as
  46 a submodule. Installing, upgrading, and rolling back changes is simple via the
  47 versioned git tags.
  48
  49 ```
  50     # Choose a global-jjb version to install
  51     GLOBAL_JJB_VERSION=v0.1.0
  52
  53     # Add the new submodule to ci-management's jjb directory.
  54     # Note: Perform once per ci-management repo.
  55     cd jjb/
  56     git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
  57
  58     # Checkout the version of global-jjb you wish to deploy.
  59     cd global-jjb
  60     git checkout $GLOBAL_JJB_VERSION
  61
  62     # Commit global-jjb version to the ci-management repo.
  63     cd ../..
  64     git add jjb/global-jjb
  65     git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
  66
  67     # Push the patch to ci-management for review
  68     git review
  69 ```
  70
  71 ## Parameters stored in defaults.yaml
  72
  73 Configure the following parameters in the ci-management repo's
  74 defaults.yaml file.
  75
  76 **gerrit-server-name**: The name of the Gerrit Server as defined
  77 in Gerrit Trigger global configuration.
  78
  79 **jenkins-ssh-credential**: The name of the Jenkins Credential to
  80 use for ssh connections.
  81
  82 If you are using GitHub then configure the following parameters
  83 in defaults.yaml
  84
  85 **git-url**: Set this to the base URL of your GitHub repo. In
  86 general this should be <https://github.com>. If you are using
  87 GitHub Enterprise, or some other GitHub-style system, then it
  88 should be whatever your installation base URL is.
  89
  90 **git-clone-url**: This is the clone prefix used by GitHub jobs.
  91 Set this to either the same thing as **git-url** or the
  92 'git@github.com:' including the trailing ':'
  93
  94 **github-org**: The name of the GitHub organization interpolated
  95 into the scm config.
  96
  97 **github_pr_org**: The name of the GitHub organization. All members
  98 of this organization will be able to trigger any job using the
  99 `lf-infra-github-pr` macro.
 100
 101 **github_pr_whitelist**: List of GitHub members you wish to be able to
 102 trigger any job that uses the `lf-infra-github-pr-trigger` macro.
 103
 104 **github_pr_admin_list**: List of GitHub members that will have admin
 105 privileges on any job using the `lf-infra-github-pr-trigger`
 106 macro.
 107
 108 defaults.yaml:
 109
 110 ```
 111 - defaults:
 112     name: global
 113
 114     # lf-infra defaults
 115     jenkins-ssh-credential: opendaylight-jenkins-ssh
 116     gerrit-server-name: OpenDaylight
 117     github-org: lfit
 118     github_pr_whitelist:
 119       - jpwku
 120       - tykeal
 121       - zxiiro
 122     github_pr_admin_list:
 123       - tykeal
 124 ```
 125
 126 ## Config File Management
 127
 128 ### Logs
 129
 130 The logs account requires a Maven Settings file created called
 131 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 132 credentials for the logs user in Nexus.
 133
 134 ## Deploying ci-jobs
 135
 136 The CI job group contains jobs that should deploy in all LF
 137 Jenkins infra. The minimal configuration needed to deploy the ci-management
 138 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
 139 defined in **lf-ci-jobs.yaml**.
 140
 141 ci-management.yaml:
 142
 143 ```
 144 - project:
 145     name: ci-jobs
 146
 147     jobs:
 148       - '{project-name}-ci-jobs'
 149
 150     project: ci-management
 151     project-name: ci-management
 152     build-node: centos7-basebuild-2c-1g
 153 ```
 154
 155 Required parameters:
 156
 157 **project**: is the project repo as defined in source control.
 158 **project-name**: is a custom name to call the job in Jenkins.
 159 **build-node**: is the name of the builder to use when building (Jenkins label).
 160
 161 Optional parameters:
 162
 163 **branch**: is the git branch to build from.
 164 **jjb-version**: is the version of JJB to install in the build minion.
 165
 166 ## Deploying packer-jobs
 167
 168 The packer job group contains jobs to build custom minion images. The minimal
 169 configuration needed to deploy the packer jobs is as follows which deploys the
 170 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
 171
 172 ci-management.yaml:
 173
 174 ```
 175 - project:
 176     name: packer-jobs
 177
 178     jobs:
 179       - '{project-name}-packer-jobs'
 180
 181     project: ci-management
 182     project-name: ci-management
 183     branch: master
 184     build-node: centos7-basebuild-2c-1g
 185
 186     platforms:
 187       - centos
 188       - ubuntu-14.04
 189       - ubuntu-16.04
 190
 191     templates:
 192       - devstack
 193       - docker
 194       - gbp
 195       - java-builder
 196       - mininet
 197
 198     exclude:
 199       - platforms: centos
 200         templates: gbp
 201       - platforms: centos
 202         templates: mininet
 203 ```
 204
 205 Required parameters:
 206
 207 **project**: is the project repo as defined in source control.
 208 **project-name**: is a custom name to call the job in Jenkins.
 209 **build-node**: is the name of the builder to use when building (Jenkins label).
 210 **platforms**: is a list of supported platforms.
 211 **templates**: is a list of supported templates.
 212
 213 Optional parameters:
 214
 215 **branch**: is the git branch to build from.
 216 **packer-version**: is the version of packer to install in the build minion,
 217 when packer is not available.
 218 **exclude**: is a combination of platforms and templates which are not required
 219 to build.
 220
 221 ## Deploying Python jobs
 222
 223 We provide the following Python jobs templates:
 224
 225 ### {project-name}-tox-verify-{stream}
 226
 227 Use this job to call python-tox to run builds and tests. The most common
 228 usage of this job is to run the Coala linter against projects.
 229
 230 ```
 231 - project:
 232     name: builder
 233     jobs:
 234         - '{project-name}-tox-verify-{stream}'
 235
 236     project-name: builder
 237     project: releng/builder
 238     build-node: centos7-java-builder-2c-4g
 239     stream: master
 240 ```
 241
 242 Required parameters:
 243
 244 **project**: is the project repo as defined in source control.
 245 **project-name**: is a custom name to call the job in Jenkins.
 246 **build-node**: is the name of the builder to use when building (Jenkins label).
 247 **stream**: typically `master` or matching the build branch. This
 248             is a useful keywords to map a release codename to a branch. For
 249             example OpenDaylight uses this to map stream=carbon to
 250             branch=stable/carbon.
 251
 252 Optional parameters:
 253
 254 **branch**: is the git branch to build from.
 255 **jjb-version**: is the version of JJB to install in the build minion.
 256 **tox-dir**: directory containing tox.ini file (default: '')
 257 **tox-envs**: tox environments to run (default: '')
 258
 259 ## Archiving logs in Jobs
 260
 261 There are 2 ways supported for archiving log information:
 262
 263 1) Job creates $WORKSPACE/archives directory and places logs there
 264
 265 This method pushes the entire archives directory to the log server
 266 in the same structure as configured in the archives directory.
 267
 268 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 269
 270 In this method a job can define a globstar for example `**/*.log` which then
 271 causes the archive script to do a globstar search for that pattern and archives
 272 any files it finds matching.
 273
 274 ## Overriding merge and verify triggers
 275
 276 The default trigger conditions for Merge and Verify job types are overrideable
 277 in a project configuration by overriding the following variables:
 278
 279 - gerrit_merge_triggers
 280 - gerrit_verify_triggers
 281
 282 These variables take a list of trigger-on values as defined in JJB docs here:
 283 <https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit>
 284
 285 ## Appendix
 286
 287 ### ShellCheck
 288
 289 When using ShellCheck to lint global-jjb or any projects that include
 290 global-jjb as part of their project (common with ci-management repos) then
 291 we require version 0.4.x of ShellCheck installed on the build vms. This version
 292 introduces annotations used by shell scripts in this repo.