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 Python jobs
 167
 168 We provide the following Python jobs templates:
 169
 170 ### {project-name}-tox-verify-{stream}
 171
 172 Use this job to call python-tox to run builds and tests. The most common
 173 usage of this job is to run the Coala linter against projects.
 174
 175 ```
 176 - project:
 177     name: builder
 178     jobs:
 179         - '{project-name}-tox-verify-{stream}'
 180
 181     project-name: builder
 182     project: releng/builder
 183     build-node: centos7-java-builder-2c-4g
 184     stream: master
 185 ```
 186
 187 Required parameters:
 188
 189 **project**: is the project repo as defined in source control.
 190 **project-name**: is a custom name to call the job in Jenkins.
 191 **build-node**: is the name of the builder to use when building (Jenkins label).
 192 **stream**: typically `master` or matching the build branch. This
 193             is a useful keywords to map a release codename to a branch. For
 194             example OpenDaylight uses this to map stream=carbon to
 195             branch=stable/carbon.
 196
 197 Optional parameters:
 198
 199 **branch**: is the git branch to build from.
 200 **jjb-version**: is the version of JJB to install in the build minion.
 201 **tox-dir**: directory containing tox.ini file (default: '')
 202 **tox-envs**: tox environments to run (default: '')
 203
 204 ## Archiving logs in Jobs
 205
 206 There are 2 ways supported for archiving log information:
 207
 208 1) Job creates $WORKSPACE/archives directory and places logs there
 209
 210 This method pushes the entire archives directory to the log server
 211 in the same structure as configured in the archives directory.
 212
 213 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 214
 215 In this method a job can define a globstar for example `**/*.log` which then
 216 causes the archive script to do a globstar search for that pattern and archives
 217 any files it finds matching.
 218
 219 ## Appendix
 220
 221 ### ShellCheck
 222
 223 When using ShellCheck to lint global-jjb or any projects that include
 224 global-jjb as part of their project (common with ci-management repos) then
 225 we require version 0.4.x of ShellCheck installed on the build vms. This version
 226 introduces annotations used by shell scripts in this repo.