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