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