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