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