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