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 Gerrit.
 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 **git-url**: is used to override the GIT_URL environment variable. Should not
 135              be necessary in most cases. Mainly used by LF projects such as
 136              global-jjb and lftools.
 137 **jjb-version**: is the version of JJB to install in the build minion.
 138
 139 ## Archiving logs in Jobs
 140
 141 There are 2 ways supported for archiving log information:
 142
 143 1) Job creates $WORKSPACE/archives directory and places logs there
 144
 145 In this method the entire archives directory will be pushed to the log server
 146 in the same structure as configured in the archives directory.
 147
 148 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
 149
 150 In this method a job can define a globstar for example ``**/*.log`` which then
 151 causes the archive script to do a globstar search for that pattern and archives
 152 any files it finds matching.