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 JENKINS_HOSTNAME=jenkins092
  15 LOGS_SERVER=https://logs.opendaylight.org
  16 NEXUS_URL=https://nexus.opendaylight.org
  17 SILO=releng
  18 ```
  19
  20 ## Jenkins Plugin Requirements
  21
  22 **Required**
  23
  24 - Config File Provider
  25 - Description Setter
  26 - Gerrit Trigger
  27 - Post Build Script
  28 - SSH Agent
  29 - Workspace Cleanup
  30
  31 **Optional**
  32
  33 - Mask Passwords
  34 - MsgInject
  35 - OpenStack Cloud
  36 - Timestamps
  37
  38 ## Installing global-jjb
  39
  40 global-jjb should be deployed in the ci-management repository's jjb directory as
  41 a submodule. global-jjb is versioned and tagged in Gerrit so installing,
  42 upgrading, and rolling back changes should be simple via the Gerrit tag system.
  43
  44 ```
  45     # Choose a global-jjb version to install
  46     GLOBAL_JJB_VERSION=v0.1.0
  47
  48     # Add the new submodule to ci-management's jjb directory.
  49     # Note: Only needs to be performed once per ci-management repo.
  50     cd jjb/
  51     git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
  52
  53     # Checkout the version of global-jjb you wish to deploy.
  54     cd global-jjb
  55     git checkout $GLOBAL_JJB_VERSION
  56
  57     # Commit global-jjb version to the ci-management repo.
  58     cd ../..
  59     git add jjb/global-jjb
  60     git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
  61
  62     # Push the patch to ci-management for review
  63     git review
  64 ```
  65
  66 ## Parameters stored in defaults.yaml
  67
  68 There are a few project specific parameters that should be stored in the
  69 ci-management repo's defaults.yaml file.
  70
  71 **gerrit-server-name**: The name of the Gerrit Server as defined in Gerrit
  72 Trigger global configuration.
  73
  74 **jenkins-ssh-credential**: The name of the Jenkins Credential to use for ssh
  75 connections.
  76
  77 If you are using GitHub then there are two more parameters which
  78 will need to be placed in the defaults.yaml
  79
  80 **github-url**: The URL of GitHub. (Default: https://github.com)
  81
  82 **github-org**: The name of the GitHub organization.
  83
  84 defaults.yaml:
  85
  86 ```
  87 - defaults:
  88     name: global
  89
  90     # lf-infra defaults
  91     jenkins-ssh-credential: opendaylight-jenkins-ssh
  92     gerrit-server-name: OpenDaylight
  93     github-org: lfit
  94 ```
  95
  96 ## Config File Management
  97
  98 ### Logs
  99
 100 The logs account requires a Maven Settings file created called
 101 **jenkins-log-archives-settings** with a server ID of **logs** containing the
 102 credentials for the logs user in Nexus.
 103
 104 ## Deploying ci-jobs
 105
 106 The CI job group contains multiple jobs that should be deployed in all LF
 107 Jenkins infra. The minimal configuration needed to deploy the ci-management
 108 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
 109 defined in **lf-ci-jobs.yaml**.
 110
 111 ci-management.yaml:
 112
 113 ```
 114 - project:
 115     name: ci-jobs
 116
 117     jobs:
 118       - '{project-name}-ci-jobs'
 119
 120     project: ci-management
 121     project-name: ci-management
 122     build-node: centos7-basebuild-2c-1g
 123 ```
 124
 125 Required parameters:
 126
 127 **project**: is the project repo as defined in source control.
 128 **project-name**: is a custom name to call the job in Jenkins.
 129 **build-node**: is the name of the builder to use when building (Jenkins label).
 130
 131 Optional parameters:
 132
 133 **branch**: is the git branch to build from.
 134 **jjb-version**: is the version of JJB to install in the build minion.
 135
 136 ## Deploying Python jobs
 137
 138 We provide the following Python jobs templates:
 139
 140 ### {project-name}-tox-verify-{stream}
 141
 142 This job can be used to call python-tox to run builds and tests. The most common
 143 usage of this job is to run the Coala linter against projects.
 144
 145 ```
 146 - project:
 147     name: builder
 148     jobs:
 149         - '{project-name}-tox-verify-{stream}'
 150
 151     project-name: builder
 152     project: releng/builder
 153     build-node: centos7-java-builder-2c-4g
 154     stream: master
 155 ```
 156
 157 Required parameters:
 158
 159 **project**: is the project repo as defined in source control.
 160 **project-name**: is a custom name to call the job in Jenkins.
 161 **build-node**: is the name of the builder to use when building (Jenkins label).
 162 **stream**: typically `master` or matching whatever branch is being built. This
 163             is a useful keywords to map a release codename to a branch. For
 164             example OpenDaylight uses this to map stream=carbon to
 165             branch=stable/carbon.
 166
 167 Optional parameters:
 168
 169 **branch**: is the git branch to build from.
 170 **jjb-version**: is the version of JJB to install in the build minion.
 171 **tox-dir**: directory containing tox.ini file (default: '')
 172 **tox-envs**: tox environments to run (default: '')
 173
 174 ## Archiving logs in Jobs
 175
 176 There are 2 ways supported for archiving log information:
 177
 178 1) Job creates $WORKSPACE/archives directory and places logs there
 179
 180 In this method the entire archives directory will be pushed to the log server
 181 in the same structure as configured in the archives directory.
 182
 183 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 184
 185 In this method a job can define a globstar for example ``**/*.log`` which then
 186 causes the archive script to do a globstar search for that pattern and archives
 187 any files it finds matching.