Enable sar report collection for global-jjb
[releng/global-jjb.git] / 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.