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