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