README.md

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