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 **lftools-version**: Version of lftools to install. Can be a specific version
 109 like '0.6.1' or a PEP-440 definition. <https://www.python.org/dev/peps/pep-0440/>
 110 For example `<1.0.0` or `>=1.0.0,<2.0.0`.
 111
 112 defaults.yaml:
 113
 114 ```
 115 - defaults:
 116     name: global
 117
 118     # lf-infra defaults
 119     jenkins-ssh-credential: opendaylight-jenkins-ssh
 120     gerrit-server-name: OpenDaylight
 121     github-org: lfit
 122     github_pr_whitelist:
 123       - jpwku
 124       - tykeal
 125       - zxiiro
 126     github_pr_admin_list:
 127       - tykeal
 128     lftools-version: '<1.0.0'
 129 ```
 130
 131 ## Config File Management
 132
 133 ### Logs
 134
 135 The logs account requires a Maven Settings file created called
 136 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 137 credentials for the logs user in Nexus.
 138
 139 ## Deploying ci-jobs
 140
 141 The CI job group contains jobs that should deploy in all LF
 142 Jenkins infra. The minimal configuration needed to deploy the ci-management
 143 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
 144 defined in **lf-ci-jobs.yaml**.
 145
 146 ci-management.yaml:
 147
 148 ```
 149 - project:
 150     name: ci-jobs
 151
 152     jobs:
 153       - '{project-name}-ci-jobs'
 154
 155     project: ci-management
 156     project-name: ci-management
 157     build-node: centos7-basebuild-2c-1g
 158 ```
 159
 160 Required parameters:
 161
 162 **project**: is the project repo as defined in source control.
 163 **project-name**: is a custom name to call the job in Jenkins.
 164 **build-node**: is the name of the builder to use when building (Jenkins label).
 165
 166 Optional parameters:
 167
 168 **branch**: is the git branch to build from.
 169 **jjb-version**: is the version of JJB to install in the build minion.
 170
 171 ## Deploying packer-jobs
 172
 173 The packer job group contains jobs to build custom minion images. The minimal
 174 configuration needed to deploy the packer jobs is as follows which deploys the
 175 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
 176
 177 ci-management.yaml:
 178
 179 ```
 180 - project:
 181     name: packer-jobs
 182
 183     jobs:
 184       - '{project-name}-packer-jobs'
 185
 186     project: ci-management
 187     project-name: ci-management
 188     branch: master
 189     build-node: centos7-basebuild-2c-1g
 190
 191     platforms:
 192       - centos
 193       - ubuntu-14.04
 194       - ubuntu-16.04
 195
 196     templates:
 197       - devstack
 198       - docker
 199       - gbp
 200       - java-builder
 201       - mininet
 202
 203     exclude:
 204       - platforms: centos
 205         templates: gbp
 206       - platforms: centos
 207         templates: mininet
 208 ```
 209
 210 Required parameters:
 211
 212 **project**: is the project repo as defined in source control.
 213 **project-name**: is a custom name to call the job in Jenkins.
 214 **build-node**: is the name of the builder to use when building (Jenkins label).
 215 **platforms**: is a list of supported platforms.
 216 **templates**: is a list of supported templates.
 217
 218 Optional parameters:
 219
 220 **branch**: is the git branch to build from.
 221 **packer-version**: is the version of packer to install in the build minion,
 222 when packer is not available.
 223 **exclude**: is a combination of platforms and templates which are not required
 224 to build.
 225
 226 ## Deploying Python jobs
 227
 228 We provide the following Python jobs templates:
 229
 230 ### {project-name}-tox-verify-{stream}
 231
 232 Use this job to call python-tox to run builds and tests. The most common
 233 usage of this job is to run the Coala linter against projects.
 234
 235 ```
 236 - project:
 237     name: builder
 238     jobs:
 239         - '{project-name}-tox-verify-{stream}'
 240
 241     project-name: builder
 242     project: releng/builder
 243     build-node: centos7-java-builder-2c-4g
 244     stream: master
 245 ```
 246
 247 Required parameters:
 248
 249 **project**: is the project repo as defined in source control.
 250 **project-name**: is a custom name to call the job in Jenkins.
 251 **build-node**: is the name of the builder to use when building (Jenkins label).
 252 **stream**: typically `master` or matching the build branch. This
 253             is a useful keywords to map a release codename to a branch. For
 254             example OpenDaylight uses this to map stream=carbon to
 255             branch=stable/carbon.
 256
 257 Optional parameters:
 258
 259 **branch**: is the git branch to build from.
 260 **jjb-version**: is the version of JJB to install in the build minion.
 261 **tox-dir**: directory containing tox.ini file (default: '')
 262 **tox-envs**: tox environments to run (default: '')
 263
 264 ## Archiving logs in Jobs
 265
 266 There are 2 ways supported for archiving log information:
 267
 268 1) Job creates $WORKSPACE/archives directory and places logs there
 269
 270 This method pushes the entire archives directory to the log server
 271 in the same structure as configured in the archives directory.
 272
 273 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 274
 275 In this method a job can define a globstar for example `**/*.log` which then
 276 causes the archive script to do a globstar search for that pattern and archives
 277 any files it finds matching.
 278
 279 ## Overriding merge and verify triggers
 280
 281 The default trigger conditions for Merge and Verify job types are overrideable
 282 in a project configuration by overriding the following variables:
 283
 284 - gerrit_merge_triggers
 285 - gerrit_verify_triggers
 286
 287 These variables take a list of trigger-on values as defined in JJB docs here:
 288 <https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit>
 289
 290 ## Appendix
 291
 292 ### ShellCheck
 293
 294 When using ShellCheck to lint global-jjb or any projects that include
 295 global-jjb as part of their project (common with ci-management repos) then
 296 we require version 0.4.x of ShellCheck installed on the build vms. This version
 297 introduces annotations used by shell scripts in this repo.