Enable maven jobs to archive artifacts
[releng/global-jjb.git] / docs / jjb / 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-common
56 ---------------
57
58 Common Jenkins configuration for Maven jobs.
59
60
61 Job Templates
62 =============
63
64 Maven CLM
65 ---------
66
67 Produces a CLM scan of the code into Nexus IQ Server.
68
69 :Template Names:
70
71     - {project-name}-maven-clm-{stream}
72     - gerrit-maven-clm
73     - github-maven-clm
74
75 :Required parameters:
76
77     :build-node:    The node to run build on.
78     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
79         be configured in defaults.yaml)
80     :mvn-settings: The name of settings file containing credentials for the project.
81
82 :Optional parameters:
83
84     :branch: The branch to build against. (default: master)
85     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
86     :build-timeout: Timeout in seconds before aborting build. (default: 60)
87     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
88     :java-version: Version of Java to use for the build. (default: openjdk8)
89     :mvn-global-settings: The name of the Maven global settings to use for
90         Maven configuration. (default: global-settings)
91     :mvn-opts: Sets MAVEN_OPTS. (default: '')
92     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
93     :mvn-version: Version of maven to use. (default: mvn33)
94     :stream: Keyword that can be used to represent a release code-name.
95         Often the same as the branch. (default: master)
96     :submodule-recursive: Whether to checkout submodules recursively.
97         (default: true)
98
99     :gerrit_merge_triggers: Override Gerrit Triggers.
100
101 Maven JavaDoc Publish
102 ---------------------
103
104 Produces and publishes javadocs for a Maven project.
105
106 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
107
108 :Template Names:
109
110     - {project-name}-maven-javadoc-publish-{stream}
111     - gerrit-maven-javadoc-publish
112     - github-maven-javadoc-publish
113
114 :Required parameters:
115
116     :build-node: The node to run build on.
117     :javadoc-path: The path in Nexus to deploy javadoc to.
118     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
119         be configured in defaults.yaml)
120     :mvn-settings: The name of settings file containing credentials for the project.
121     :mvn-site-id: Maven Server ID from settings.xml to pull credentials from.
122         (Note: This setting should be configured in defaults.yaml.)
123
124 :Optional parameters:
125
126     :branch: The branch to build against. (default: master)
127     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
128     :build-timeout: Timeout in seconds before aborting build. (default: 60)
129     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
130     :java-version: Version of Java to use for the build. (default: openjdk8)
131     :mvn-global-settings: The name of the Maven global settings to use for
132         Maven configuration. (default: global-settings)
133     :mvn-opts: Sets MAVEN_OPTS. (default: '')
134     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
135     :mvn-version: Version of maven to use. (default: mvn33)
136     :stream: Keyword that can be used to represent a release code-name.
137         Often the same as the branch. (default: master)
138     :submodule-recursive: Whether to checkout submodules recursively.
139         (default: true)
140
141     :gerrit_merge_triggers: Override Gerrit Triggers.
142
143 Maven JavaDoc Verify
144 --------------------
145
146 Produces javadocs for a Maven project.
147
148 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
149
150 :Template Names:
151
152     - {project-name}-maven-javadoc-verify-{stream}
153     - gerrit-maven-javadoc-verify
154     - github-maven-javadoc-verify
155
156 :Required parameters:
157     :build-node:    The node to run build on.
158     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
159         be configured in defaults.yaml)
160     :mvn-settings: The name of settings file containing credentials for the project.
161
162 :Optional parameters:
163
164     :branch: The branch to build against. (default: master)
165     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
166     :build-timeout: Timeout in seconds before aborting build. (default: 60)
167     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
168     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
169     :java-version: Version of Java to use for the build. (default: openjdk8)
170     :mvn-global-settings: The name of the Maven global settings to use for
171         Maven configuration. (default: global-settings)
172     :mvn-opts: Sets MAVEN_OPTS. (default: '')
173     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
174     :mvn-version: Version of maven to use. (default: mvn33)
175     :stream: Keyword that can be used to represent a release code-name.
176         Often the same as the branch. (default: master)
177     :submodule-recursive: Whether to checkout submodules recursively.
178         (default: true)
179
180     :gerrit_verify_triggers: Override Gerrit Triggers.
181
182 Maven Release
183 -------------
184
185 Produces a release candidate by creating a staging repo in Nexus.
186
187 Runs a Maven build and deploys to $WORKSPACE/m2repo directory. This
188 directory can then be reused later to deploy to Nexus.
189
190 :Template Names:
191
192     - {project-name}-maven-release-{stream}
193     - gerrit-maven-release
194     - github-maven-release
195
196 :Required parameters:
197
198     :build-node: The node to run build on.
199     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
200         be configured in defaults.yaml)
201     :mvn-settings: The name of settings file containing credentials for the project.
202     :mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
203         (Note: This setting should be configured in defaults.yaml.)
204     :staging-profile-id: Profile ID of the project's Nexus staging profile.
205
206 :Optional parameters:
207
208     :archive-artifacts: Artifacts to archive to the logs server (default: ''). 
209     :branch: The branch to build against. (default: master)
210     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
211     :build-timeout: Timeout in seconds before aborting build. (default: 60)
212     :cron: Cron schedule when to trigger the job. This parameter also
213         supports multiline input via YAML pipe | character in cases where
214         one may want to provide more than 1 cron timer. (default: '')
215     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
216     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
217     :java-version: Version of Java to use for the build. (default: openjdk8)
218     :mvn-global-settings: The name of the Maven global settings to use for
219         Maven configuration. (default: global-settings)
220     :mvn-opts: Sets MAVEN_OPTS. (default: '')
221     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
222     :mvn-version: Version of maven to use. (default: mvn33)
223     :stream: Keyword that can be used to represent a release code-name.
224         Often the same as the branch. (default: master)
225     :submodule-recursive: Whether to checkout submodules recursively.
226         (default: true)
227
228     :gerrit_release_triggers: Override Gerrit Triggers.
229
230 Maven Sonar
231 -----------
232
233 Sonar job which runs mvn clean install then publishes to Sonar.
234
235 This job purposely only runs on the master branch as there are Additional
236 configuration needed to support multiple branches and there's not much
237 interest in that kind of support.
238
239 :Template Names:
240
241     - {project-name}-sonar
242     - gerrit-maven-sonar
243     - github-maven-sonar
244
245 :Required parameters:
246
247     :build-node: The node to run build on.
248     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
249         be configured in defaults.yaml)
250     :mvn-settings: The name of settings file containing credentials for the project.
251
252 :Optional parameters:
253
254     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
255     :build-timeout: Timeout in seconds before aborting build. (default: 60)
256     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
257     :java-version: Version of Java to use for the build. (default: openjdk8)
258     :mvn-global-settings: The name of the Maven global settings to use for
259         Maven configuration. (default: global-settings)
260     :mvn-opts: Sets MAVEN_OPTS. (default: '')
261     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
262     :mvn-version: Version of maven to use. (default: mvn33)
263     :stream: Keyword that can be used to represent a release code-name.
264         Often the same as the branch. (default: master)
265     :submodule-recursive: Whether to checkout submodules recursively.
266         (default: true)
267
268     :gerrit_sonar_triggers: Override Gerrit Triggers.
269
270 Maven Verify
271 ------------
272
273 Verify job which runs mvn clean install to test a project build..
274
275 :Template Names:
276
277     - {project-name}-maven-verify-{stream}-{mvn-version}-{java-version}
278     - gerrit-maven-verify
279     - github-maven-verify
280
281 :Required parameters:
282
283     :build-node: The node to run build on.
284     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
285         be configured in defaults.yaml)
286     :mvn-settings: The name of settings file containing credentials for the project.
287
288 :Optional parameters:
289
290     :branch: Git branch to fetch for the build. (default: master)
291     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
292     :build-timeout: Timeout in seconds before aborting build. (default: 60)
293     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
294     :java-version: Version of Java to use for the build. (default: openjdk8)
295     :mvn-global-settings: The name of the Maven global settings to use for
296         Maven configuration. (default: global-settings)
297     :mvn-opts: Sets MAVEN_OPTS. (default: '')
298     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
299     :mvn-version: Version of maven to use. (default: mvn33)
300     :stream: Keyword that can be used to represent a release code-name.
301         Often the same as the branch. (default: master)
302     :submodule-recursive: Whether to checkout submodules recursively.
303         (default: true)
304
305     :gerrit_verify_triggers: Override Gerrit Triggers.
306     :gerrit_trigger_file_paths: Override file paths which can be used to
307         filter which file modifications will trigger a build.
308
309 Maven Verify /w Dependencies
310 ----------------------------
311
312 Verify job which runs mvn clean install to test a project build /w deps
313
314 This job can be used to verify a patch in conjunction to all of the
315 upstream patches it depends on. The user of this job can provide a list
316 via comment trigger.
317
318 :Template Names:
319
320     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
321     - gerrit-maven-verify-dependencies
322
323 :Comment Trigger: recheck: SPACE_SEPERATED_LIST_OF_PATCHES
324
325 :Required parameters:
326
327     :build-node: The node to run build on.
328     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
329         be configured in defaults.yaml)
330     :mvn-settings: The name of settings file containing credentials for the project.
331
332 :Optional parameters:
333
334     :branch: Git branch to fetch for the build. (default: master)
335     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
336     :build-timeout: Timeout in seconds before aborting build. (default: 60)
337     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
338     :java-version: Version of Java to use for the build. (default: openjdk8)
339     :mvn-global-settings: The name of the Maven global settings to use for
340         Maven configuration. (default: global-settings)
341     :mvn-opts: Sets MAVEN_OPTS. (default: '')
342     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
343     :mvn-version: Version of maven to use. (default: mvn33)
344     :stream: Keyword that can be used to represent a release code-name.
345         Often the same as the branch. (default: master)
346     :submodule-recursive: Whether to checkout submodules recursively.
347         (default: true)
348
349     :gerrit_verify_triggers: Override Gerrit Triggers.
350     :gerrit_trigger_file_paths: Override file paths which can be used to
351         filter which file modifications will trigger a build.