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 defaults.yaml
  74 file.
  75
  76 **gerrit-server-name**: The name of the Gerrit Server as defined in Gerrit
  77 Trigger global configuration.
  78
  79 **jenkins-ssh-credential**: The name of the Jenkins Credential to use for ssh
  80 connections.
  81
  82 If you are using GitHub then configure the following parameters in defaults.yaml
  83
  84 **git-url**: Set this to the base URL of your GitHub repo. In
  85 general this should be <https://github.com>. If you are using GitHub
  86 Enterprise, or some other GitHub-style system, then it should be
  87 whatever your installation base URL is.
  88
  89 **git-clone-url**: This is the clone prefix used by GitHub jobs. Set this to
  90 either the same thing as **git-url** or the
  91 'git@github.com:' including the trailing ':'
  92
  93 **github-org**: The name of the GitHub organization.
  94
  95 defaults.yaml:
  96
  97 ```
  98 - defaults:
  99     name: global
 100
 101     # lf-infra defaults
 102     jenkins-ssh-credential: opendaylight-jenkins-ssh
 103     gerrit-server-name: OpenDaylight
 104     github-org: lfit
 105 ```
 106
 107 ## Config File Management
 108
 109 ### Logs
 110
 111 The logs account requires a Maven Settings file created called
 112 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 113 credentials for the logs user in Nexus.
 114
 115 ## Deploying ci-jobs
 116
 117 The CI job group contains jobs that should deploy in all LF
 118 Jenkins infra. The minimal configuration needed to deploy the ci-management
 119 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
 120 defined in **lf-ci-jobs.yaml**.
 121
 122 ci-management.yaml:
 123
 124 ```
 125 - project:
 126     name: ci-jobs
 127
 128     jobs:
 129       - '{project-name}-ci-jobs'
 130
 131     project: ci-management
 132     project-name: ci-management
 133     build-node: centos7-basebuild-2c-1g
 134 ```
 135
 136 Required parameters:
 137
 138 **project**: is the project repo as defined in source control.
 139 **project-name**: is a custom name to call the job in Jenkins.
 140 **build-node**: is the name of the builder to use when building (Jenkins label).
 141
 142 Optional parameters:
 143
 144 **branch**: is the git branch to build from.
 145 **jjb-version**: is the version of JJB to install in the build minion.
 146
 147 ## Deploying Python jobs
 148
 149 We provide the following Python jobs templates:
 150
 151 ### {project-name}-tox-verify-{stream}
 152
 153 Use this job to call python-tox to run builds and tests. The most common
 154 usage of this job is to run the Coala linter against projects.
 155
 156 ```
 157 - project:
 158     name: builder
 159     jobs:
 160         - '{project-name}-tox-verify-{stream}'
 161
 162     project-name: builder
 163     project: releng/builder
 164     build-node: centos7-java-builder-2c-4g
 165     stream: master
 166 ```
 167
 168 Required parameters:
 169
 170 **project**: is the project repo as defined in source control.
 171 **project-name**: is a custom name to call the job in Jenkins.
 172 **build-node**: is the name of the builder to use when building (Jenkins label).
 173 **stream**: typically `master` or matching the build branch. This
 174             is a useful keywords to map a release codename to a branch. For
 175             example OpenDaylight uses this to map stream=carbon to
 176             branch=stable/carbon.
 177
 178 Optional parameters:
 179
 180 **branch**: is the git branch to build from.
 181 **jjb-version**: is the version of JJB to install in the build minion.
 182 **tox-dir**: directory containing tox.ini file (default: '')
 183 **tox-envs**: tox environments to run (default: '')
 184
 185 ## Archiving logs in Jobs
 186
 187 There are 2 ways supported for archiving log information:
 188
 189 1) Job creates $WORKSPACE/archives directory and places logs there
 190
 191 This method pushes the entire archives directory to the log server
 192 in the same structure as configured in the archives directory.
 193
 194 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 195
 196 In this method a job can define a globstar for example `**/*.log` which then
 197 causes the archive script to do a globstar search for that pattern and archives
 198 any files it finds matching.
 199
 200 ## Appendix
 201
 202 ### ShellCheck
 203
 204 When using ShellCheck to lint global-jjb or any projects that include
 205 global-jjb as part of their project (common with ci-management repos) then
 206 we require version 0.4.x of ShellCheck installed on the build vms. This version
 207 introduces annotations used by shell scripts in this repo.