Merge "Fix jjb-verify job to ignore the docs directory"
[releng/global-jjb.git] / README.md
1 # Global JJB
2
3 The purpose of this repository is store generically defined, reusable JJB
4 templates, deployable across LF projects.
5
6 Define the following variables 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 GERRIT_URL=https://git.opendaylight.org/gerrit
14 GIT_URL=ssh://jenkins-$SILO@git.opendaylight.org:29418
15 GIT_CLONE_URL=git@github.com:
16 JENKINS_HOSTNAME=jenkins092
17 LOGS_SERVER=https://logs.opendaylight.org
18 NEXUS_URL=https://nexus.opendaylight.org
19 SILO=releng
20 SONAR_URL=https://sonar.opendaylight.org
21 ```
22
23 Note: Use **GIT_CLONE_URL** for GitHub projects as this
24 will be different from the URL used the poperties
25 configuration.
26
27 ## Jenkins Plugin Requirements
28
29 **Required**
30
31 - Config File Provider
32 - Description Setter
33 - Environment Injector Plugin
34 - Git plugin
35 - Post Build Script
36 - SSH Agent
37 - Workspace Cleanup
38
39 **Required for Gerrit connected systems**
40
41 - Gerrit Trigger
42
43 **Required for GitHub connected systems**
44
45 - GitHub plugin
46 - GitHub Pull Request Builder
47
48 **Optional**
49
50 - Mask Passwords
51 - MsgInject
52 - OpenStack Cloud
53 - Timestamps
54
55 ## Installing global-jjb
56
57 Deploy global-jjb in the ci-management repository's jjb directory as
58 a submodule. Installing, upgrading, and rolling back changes is simple via the
59 versioned git tags.
60
61 ```
62     # Choose a global-jjb version to install
63     GLOBAL_JJB_VERSION=v0.1.0
64
65     # Add the new submodule to ci-management's jjb directory.
66     # Note: Perform once per ci-management repo.
67     cd jjb/
68     git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
69
70     # Checkout the version of global-jjb you wish to deploy.
71     cd global-jjb
72     git checkout $GLOBAL_JJB_VERSION
73
74     # Commit global-jjb version to the ci-management repo.
75     cd ../..
76     git add jjb/global-jjb
77     git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
78
79     # Push the patch to ci-management for review
80     git review
81 ```
82
83 ## Parameters stored in defaults.yaml
84
85 Configure the following parameters in the ci-management repo's
86 defaults.yaml file.
87
88 **gerrit-server-name**: The name of the Gerrit Server as defined
89 in Gerrit Trigger global configuration.
90
91 **jenkins-ssh-credential**: The name of the Jenkins Credential to
92 use for ssh connections.
93
94 If you are using GitHub then configure the following parameters
95 in defaults.yaml
96
97 **git-url**: Set this to the base URL of your GitHub repo. In
98 general this should be <https://github.com>. If you are using
99 GitHub Enterprise, or some other GitHub-style system, then it
100 should be whatever your installation base URL is.
101
102 **git-clone-url**: This is the clone prefix used by GitHub jobs.
103 Set this to either the same thing as **git-url** or the
104 'git@github.com:' including the trailing ':'
105
106 **github-org**: The name of the GitHub organization interpolated
107 into the scm config.
108
109 **github_pr_org**: The name of the GitHub organization. All members
110 of this organization will be able to trigger any job using the
111 `lf-infra-github-pr` macro.
112
113 **github_pr_whitelist**: List of GitHub members you wish to be able to
114 trigger any job that uses the `lf-infra-github-pr-trigger` macro.
115
116 **github_pr_admin_list**: List of GitHub members that will have admin
117 privileges on any job using the `lf-infra-github-pr-trigger`
118 macro.
119
120 **lftools-version**: Version of lftools to install. Can be a specific version
121 like '0.6.1' or a PEP-440 definition. <https://www.python.org/dev/peps/pep-0440/>
122 For example `<1.0.0` or `>=1.0.0,<2.0.0`.
123
124 **mvn-site-id**: Maven Server ID from settings.xml containing the credentials
125 to push to a Maven site repository.
126
127 **mvn-staging-id**: Maven Server ID from settings.xml containing the credentials
128 to push to a Maven staging repository.
129
130 defaults.yaml:
131
132 ```
133 - defaults:
134     name: global
135
136     # lf-infra defaults
137     jenkins-ssh-credential: opendaylight-jenkins-ssh
138     gerrit-server-name: OpenDaylight
139     github-org: lfit
140     github_pr_whitelist:
141       - jpwku
142       - tykeal
143       - zxiiro
144     github_pr_admin_list:
145       - tykeal
146     lftools-version: '<1.0.0'
147     mvn-site-id: opendaylight-site
148 ```
149
150 ## Config File Management
151
152 ### Logs
153
154 The logs account requires a Maven Settings file created called
155 **jenkins-log-archives-settings** with a server ID of **logs** containing the
156 credentials for the logs user in Nexus.
157
158 ## Deploying ci-jobs
159
160 The CI job group contains jobs that should deploy in all LF
161 Jenkins infra. The minimal configuration needed to deploy the ci-management
162 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
163 defined in **lf-ci-jobs.yaml**.
164
165 ci-management.yaml:
166
167 ```
168 - project:
169     name: ci-jobs
170
171     jobs:
172       - '{project-name}-ci-jobs'
173
174     project: ci-management
175     project-name: ci-management
176     build-node: centos7-basebuild-2c-1g
177 ```
178
179 Required parameters:
180
181 **project**: is the project repo as defined in source control.
182 **project-name**: is a custom name to call the job in Jenkins.
183 **build-node**: is the name of the builder to use when building (Jenkins label).
184
185 Optional parameters:
186
187 **branch**: is the git branch to build from.
188 **jjb-version**: is the version of JJB to install in the build minion.
189
190 ## Deploying packer-jobs
191
192 The packer job group contains jobs to build custom minion images. The minimal
193 configuration needed to deploy the packer jobs is as follows which deploys the
194 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
195
196 ci-management.yaml:
197
198 ```
199 - project:
200     name: packer-jobs
201
202     jobs:
203       - '{project-name}-packer-jobs'
204
205     project: ci-management
206     project-name: ci-management
207     branch: master
208     build-node: centos7-basebuild-2c-1g
209
210     platforms:
211       - centos
212       - ubuntu-14.04
213       - ubuntu-16.04
214
215     templates:
216       - devstack
217       - docker
218       - gbp
219       - java-builder
220       - mininet
221
222     exclude:
223       - platforms: centos
224         templates: gbp
225       - platforms: centos
226         templates: mininet
227 ```
228
229 Required parameters:
230
231 **project**: is the project repo as defined in source control.
232 **project-name**: is a custom name to call the job in Jenkins.
233 **build-node**: is the name of the builder to use when building (Jenkins label).
234 **platforms**: is a list of supported platforms.
235 **templates**: is a list of supported templates.
236
237 Optional parameters:
238
239 **branch**: is the git branch to build from.
240 **packer-version**: is the version of packer to install in the build minion,
241 when packer is not available.
242 **exclude**: is a combination of platforms and templates which are not required
243 to build.
244
245 ## Deploying Python jobs
246
247 We provide the following Python jobs templates:
248
249 ### {project-name}-tox-verify-{stream}
250
251 Use this job to call python-tox to run builds and tests. The most common
252 usage of this job is to run the Coala linter against projects.
253
254 ```
255 - project:
256     name: builder
257     jobs:
258         - '{project-name}-tox-verify-{stream}'
259
260     project-name: builder
261     project: releng/builder
262     build-node: centos7-java-builder-2c-4g
263     stream: master
264 ```
265
266 Required parameters:
267
268 **project**: is the project repo as defined in source control.
269 **project-name**: is a custom name to call the job in Jenkins.
270 **build-node**: is the name of the builder to use when building (Jenkins label).
271 **stream**: typically `master` or matching the build branch. This
272             is a useful keywords to map a release codename to a branch. For
273             example OpenDaylight uses this to map stream=carbon to
274             branch=stable/carbon.
275
276 Optional parameters:
277
278 **branch**: is the git branch to build from.
279 **jjb-version**: is the version of JJB to install in the build minion.
280 **tox-dir**: directory containing tox.ini file (default: '')
281 **tox-envs**: tox environments to run (default: '')
282
283 ## Archiving logs in Jobs
284
285 There are 2 ways supported for archiving log information:
286
287 1) Job creates $WORKSPACE/archives directory and places logs there
288
289 This method pushes the entire archives directory to the log server
290 in the same structure as configured in the archives directory.
291
292 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
293
294 In this method a job can define a globstar for example `**/*.log` which then
295 causes the archive script to do a globstar search for that pattern and archives
296 any files it finds matching.
297
298 ## Overriding merge and verify triggers
299
300 The default trigger conditions for Merge and Verify job types are overrideable
301 in a project configuration by overriding the following variables:
302
303 - gerrit_merge_triggers
304 - gerrit_verify_triggers
305
306 These variables take a list of trigger-on values as defined in JJB docs here:
307 <https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit>
308
309 ## Appendix
310
311 ### ShellCheck
312
313 When using ShellCheck to lint global-jjb or any projects that include
314 global-jjb as part of their project (common with ci-management repos) then
315 we require version 0.4.x of ShellCheck installed on the build vms. This version
316 introduces annotations used by shell scripts in this repo.