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