939aaf8b59cb5bfacba48e48ef2009ec3e0129c4
[releng/global-jjb.git] / lf-maven-jobs.rst
1 ##########
2 Maven Jobs
3 ##########
4
5 Job Groups
6 ==========
7
8 {project-name}-maven-jobs
9 -------------------------
10
11 Jobs for Maven projects using Gerrit.
12
13 :Includes:
14
15     - gerrit-maven-clm
16     - gerrit-maven-release
17     - gerrit-maven-verify
18     - gerrit-maven-verify-dependencies
19
20 {project-name}-github-maven-jobs
21 --------------------------------
22
23 Jobs for Maven projects using GitHub.
24
25 :Includes:
26
27     - github-maven-clm
28     - github-maven-release
29     - github-maven-verify
30
31 {project-name}-maven-javadoc-jobs
32 ---------------------------------
33
34 Jobs for Maven projects to generate javadoc using Gerrit.
35
36 :Includes:
37
38     - gerrit-maven-javadoc-publish
39     - gerrit-maven-javadoc-verify
40
41 {project-name}-github-maven-javadoc-jobs
42 ----------------------------------------
43
44 Jobs for Maven projects to generate javadoc using GitHub.
45
46 :Includes:
47
48     - github-maven-javadoc-publish
49     - github-maven-javadoc-verify
50
51
52 Macros
53 ======
54
55 lf-maven-build
56 --------------
57
58 Calls the maven build script to perform a maven build.
59
60 :Required parameters:
61
62     :mvn-goals: The maven goals to perform for the build.
63         (default: clean deploy)
64
65 lf-maven-common
66 ---------------
67
68 Common Jenkins configuration for Maven jobs.
69
70 lf-maven-deploy
71 ---------------
72
73 Calls the maven deploy script to push artifacts to Nexus.
74
75 lf-maven-stage
76 ---------------
77
78 Calls the maven stage script to push artifacts to a Nexus staging repository.
79
80 Job Templates
81 =============
82
83 Maven CLM
84 ---------
85
86 Produces a CLM scan of the code into Nexus IQ Server.
87
88 :Template Names:
89
90     - {project-name}-maven-clm-{stream}
91     - gerrit-maven-clm
92     - github-maven-clm
93
94 :Required parameters:
95
96     :build-node:    The node to run build on.
97     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
98         be configured in defaults.yaml)
99     :mvn-settings: The name of settings file containing credentials for the project.
100
101 :Optional parameters:
102
103     :branch: The branch to build against. (default: master)
104     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
105     :build-timeout: Timeout in seconds before aborting build. (default: 60)
106     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
107     :java-version: Version of Java to use for the build. (default: openjdk8)
108     :mvn-global-settings: The name of the Maven global settings to use for
109         Maven configuration. (default: global-settings)
110     :mvn-opts: Sets MAVEN_OPTS. (default: '')
111     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
112     :mvn-version: Version of maven to use. (default: mvn33)
113     :stream: Keyword that can be used to represent a release code-name.
114         Often the same as the branch. (default: master)
115     :submodule-recursive: Whether to checkout submodules recursively.
116         (default: true)
117
118     :gerrit_merge_triggers: Override Gerrit Triggers.
119
120 Maven JavaDoc Publish
121 ---------------------
122
123 Produces and publishes javadocs for a Maven project.
124
125 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
126
127 :Template Names:
128
129     - {project-name}-maven-javadoc-publish-{stream}
130     - gerrit-maven-javadoc-publish
131     - github-maven-javadoc-publish
132
133 :Required parameters:
134
135     :build-node: The node to run build on.
136     :javadoc-path: The path in Nexus to deploy javadoc to.
137     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
138         be configured in defaults.yaml)
139     :mvn-settings: The name of settings file containing credentials for the project.
140     :mvn-site-id: Maven Server ID from settings.xml to pull credentials from.
141         (Note: This setting should be configured in defaults.yaml.)
142
143 :Optional parameters:
144
145     :branch: The branch to build against. (default: master)
146     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
147     :build-timeout: Timeout in seconds before aborting build. (default: 60)
148     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
149     :java-version: Version of Java to use for the build. (default: openjdk8)
150     :mvn-global-settings: The name of the Maven global settings to use for
151         Maven configuration. (default: global-settings)
152     :mvn-opts: Sets MAVEN_OPTS. (default: '')
153     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
154     :mvn-version: Version of maven to use. (default: mvn33)
155     :stream: Keyword that can be used to represent a release code-name.
156         Often the same as the branch. (default: master)
157     :submodule-recursive: Whether to checkout submodules recursively.
158         (default: true)
159
160     :gerrit_merge_triggers: Override Gerrit Triggers.
161
162 Maven JavaDoc Verify
163 --------------------
164
165 Produces javadocs for a Maven project.
166
167 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
168
169 :Template Names:
170
171     - {project-name}-maven-javadoc-verify-{stream}
172     - gerrit-maven-javadoc-verify
173     - github-maven-javadoc-verify
174
175 :Required parameters:
176     :build-node:    The node to run build on.
177     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
178         be configured in defaults.yaml)
179     :mvn-settings: The name of settings file containing credentials for the project.
180
181 :Optional parameters:
182
183     :branch: The branch to build against. (default: master)
184     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
185     :build-timeout: Timeout in seconds before aborting build. (default: 60)
186     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
187     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
188     :java-version: Version of Java to use for the build. (default: openjdk8)
189     :mvn-global-settings: The name of the Maven global settings to use for
190         Maven configuration. (default: global-settings)
191     :mvn-opts: Sets MAVEN_OPTS. (default: '')
192     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
193     :mvn-version: Version of maven to use. (default: mvn33)
194     :stream: Keyword that can be used to represent a release code-name.
195         Often the same as the branch. (default: master)
196     :submodule-recursive: Whether to checkout submodules recursively.
197         (default: true)
198
199     :gerrit_verify_triggers: Override Gerrit Triggers.
200
201 Maven Merge
202 -----------
203
204 Merge job which runs `mvn clean deploy` to build a project.
205
206 This job pushes files to Nexus using cURL instead of allowing the Maven deploy
207 goal to push the upload. This is to get around the issue that Maven deploy does
208 not properly support uploading files at the end of the build and instead pushes
209 as it goes. There exists a `-Ddeploy-at-end` feature however it does not work
210 with extensions.
211
212 This job uses the following strategy to deploy jobs to Nexus:
213
214 1. `wget -r` to fetch maven-metadata.xml from Nexus
215 2. `mvn deploy -DaltDeploymentRepository` to prepare files for upload
216 3. Removes untouched maven-metadata.xml files before upload
217 4. Use lftools (cURL) upload script to push artifacts to Nexus
218
219 :Template Names:
220
221     - {project-name}-maven-merge-{stream}
222     - gerrit-maven-merge
223     - github-maven-merge
224
225 :Required parameters:
226
227     :build-node: The node to run build on.
228     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
229         be configured in defaults.yaml)
230     :mvn-settings: The name of settings file containing credentials for the project.
231     :mvn-snapshot-id: Maven Server ID from settings.xml to pull credentials from.
232         (Note: This setting should be configured in defaults.yaml.)
233     :nexus-snapshot-repo: The repository id of the Nexus snapshot repo to deploy to.
234
235 :Optional parameters:
236
237     :branch: Git branch to fetch for the build. (default: master)
238     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
239     :build-timeout: Timeout in seconds before aborting build. (default: 60)
240     :cron: Cron schedule when to trigger the job. This parameter also
241         supports multiline input via YAML pipe | character in cases where
242         one may want to provide more than 1 cron timer. (default: 'H H * * 0'
243         to run weekly)
244     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
245     :java-version: Version of Java to use for the build. (default: openjdk8)
246     :mvn-global-settings: The name of the Maven global settings to use for
247         Maven configuration. (default: global-settings)
248     :mvn-opts: Sets MAVEN_OPTS. (default: '')
249     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
250     :mvn-version: Version of maven to use. (default: mvn33)
251     :nexus-cut-dirs: Number of directories to cut from file path for `wget -r`.
252     :stream: Keyword that can be used to represent a release code-name.
253         Often the same as the branch. (default: master)
254     :submodule-recursive: Whether to checkout submodules recursively.
255         (default: true)
256
257     :gerrit_merge_triggers: Override Gerrit Triggers.
258     :gerrit_trigger_file_paths: Override file paths which can be used to
259         filter which file modifications will trigger a build.
260
261 Maven Release
262 -------------
263
264 Produces a release candidate by creating a staging repo in Nexus.
265
266 Runs a Maven build and deploys to $WORKSPACE/m2repo directory. This
267 directory can then be reused later to deploy to Nexus.
268
269 :Template Names:
270
271     - {project-name}-maven-release-{stream}
272     - gerrit-maven-release
273     - github-maven-release
274
275 :Required parameters:
276
277     :build-node: The node to run build on.
278     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
279         be configured in defaults.yaml)
280     :mvn-settings: The name of settings file containing credentials for the project.
281     :mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
282         (Note: This setting should be configured in defaults.yaml.)
283     :staging-profile-id: Profile ID of the project's Nexus staging profile.
284
285 :Optional parameters:
286
287     :archive-artifacts: Artifacts to archive to the logs server (default: '').
288     :branch: The branch to build against. (default: master)
289     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
290     :build-timeout: Timeout in seconds before aborting build. (default: 60)
291     :cron: Cron schedule when to trigger the job. This parameter also
292         supports multiline input via YAML pipe | character in cases where
293         one may want to provide more than 1 cron timer. (default: '')
294     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
295     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
296     :java-version: Version of Java to use for the build. (default: openjdk8)
297     :mvn-global-settings: The name of the Maven global settings to use for
298         Maven configuration. (default: global-settings)
299     :mvn-opts: Sets MAVEN_OPTS. (default: '')
300     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
301     :mvn-version: Version of maven to use. (default: mvn33)
302     :stream: Keyword that can be used to represent a release code-name.
303         Often the same as the branch. (default: master)
304     :submodule-recursive: Whether to checkout submodules recursively.
305         (default: true)
306
307     :gerrit_release_triggers: Override Gerrit Triggers.
308
309 Maven Sonar
310 -----------
311
312 Sonar job which runs mvn clean install then publishes to Sonar.
313
314 This job purposely only runs on the master branch as there are Additional
315 configuration needed to support multiple branches and there's not much
316 interest in that kind of support.
317
318 :Template Names:
319
320     - {project-name}-sonar
321     - gerrit-maven-sonar
322     - github-maven-sonar
323
324 :Required parameters:
325
326     :build-node: The node to run build on.
327     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
328         be configured in defaults.yaml)
329     :mvn-settings: The name of settings file containing credentials for the project.
330
331 :Optional parameters:
332
333     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
334     :build-timeout: Timeout in seconds before aborting build. (default: 60)
335     :cron: Cron schedule when to trigger the job. This parameter also
336         supports multiline input via YAML pipe | character in cases where
337         one may want to provide more than 1 cron timer.  (default: 'H H * * 6'
338         to run weekly)
339     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
340     :java-version: Version of Java to use for the build. (default: openjdk8)
341     :mvn-global-settings: The name of the Maven global settings to use for
342         Maven configuration. (default: global-settings)
343     :mvn-opts: Sets MAVEN_OPTS. (default: '')
344     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
345     :mvn-version: Version of maven to use. (default: mvn33)
346     :stream: Keyword that can be used to represent a release code-name.
347         Often the same as the branch. (default: master)
348     :submodule-recursive: Whether to checkout submodules recursively.
349         (default: true)
350
351     :gerrit_sonar_triggers: Override Gerrit Triggers.
352
353 Maven Verify
354 ------------
355
356 Verify job which runs mvn clean install to test a project build..
357
358 :Template Names:
359
360     - {project-name}-maven-verify-{stream}-{mvn-version}-{java-version}
361     - gerrit-maven-verify
362     - github-maven-verify
363
364 :Required parameters:
365
366     :build-node: The node to run build on.
367     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
368         be configured in defaults.yaml)
369     :mvn-settings: The name of settings file containing credentials for the project.
370
371 :Optional parameters:
372
373     :branch: Git branch to fetch for the build. (default: master)
374     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
375     :build-timeout: Timeout in seconds before aborting build. (default: 60)
376     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
377     :java-version: Version of Java to use for the build. (default: openjdk8)
378     :mvn-global-settings: The name of the Maven global settings to use for
379         Maven configuration. (default: global-settings)
380     :mvn-opts: Sets MAVEN_OPTS. (default: '')
381     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
382     :mvn-version: Version of maven to use. (default: mvn33)
383     :stream: Keyword that can be used to represent a release code-name.
384         Often the same as the branch. (default: master)
385     :submodule-recursive: Whether to checkout submodules recursively.
386         (default: true)
387
388     :gerrit_verify_triggers: Override Gerrit Triggers.
389     :gerrit_trigger_file_paths: Override file paths which can be used to
390         filter which file modifications will trigger a build.
391
392 Maven Verify /w Dependencies
393 ----------------------------
394
395 Verify job which runs mvn clean install to test a project build /w deps
396
397 This job can be used to verify a patch in conjunction to all of the
398 upstream patches it depends on. The user of this job can provide a list
399 via comment trigger.
400
401 :Template Names:
402
403     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
404     - gerrit-maven-verify-dependencies
405
406 :Comment Trigger: recheck: SPACE_SEPERATED_LIST_OF_PATCHES
407
408 :Required parameters:
409
410     :build-node: The node to run build on.
411     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
412         be configured in defaults.yaml)
413     :mvn-settings: The name of settings file containing credentials for the project.
414
415 :Optional parameters:
416
417     :branch: Git branch to fetch for the build. (default: master)
418     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
419     :build-timeout: Timeout in minutes before aborting build. (default: 60)
420     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
421     :java-version: Version of Java to use for the build. (default: openjdk8)
422     :mvn-global-settings: The name of the Maven global settings to use for
423         Maven configuration. (default: global-settings)
424     :mvn-opts: Sets MAVEN_OPTS. (default: '')
425     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
426     :mvn-version: Version of maven to use. (default: mvn33)
427     :stream: Keyword that can be used to represent a release code-name.
428         Often the same as the branch. (default: master)
429     :submodule-recursive: Whether to checkout submodules recursively.
430         (default: true)
431
432     :gerrit_verify_triggers: Override Gerrit Triggers.
433     :gerrit_trigger_file_paths: Override file paths which can be used to
434         filter which file modifications will trigger a build.