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