Add a note about requiring jjbini configuration
[releng/global-jjb.git] / docs / jjb / lf-ci-jobs.rst
1 #######
2 CI Jobs
3 #######
4
5 Job Groups
6 ==========
7
8 {project-name}-ci-jobs
9 ----------------------
10
11 Recommended jobs that should be deployed for CI using Gerrit.
12
13 :Includes:
14
15     - gerrit-jenkins-cfg-merge
16     - gerrit-jjb-deploy-job
17     - gerrit-jjb-merge
18     - gerrit-jjb-verify
19
20 {project-name}-github-ci-jobs
21 -----------------------------
22
23 Recommended jobs that should be deployed CI using GitHub.
24
25 :Includes:
26
27     - github-jenkins-cfg-merge
28     - github-jjb-deploy-job
29     - github-jjb-merge
30     - github-jjb-verify
31
32 {project-name}-packer-jobs
33 --------------------------
34
35 Jobs related to Packer builds for CI using Gerrit.
36
37 :Includes:
38
39     - gerrit-packer-merge
40     - gerrit-packer-verify
41
42 {project-name}-github-packer-jobs
43 ---------------------------------
44
45 Jobs related to Packer builds for CI using GitHub.
46
47 :Includes:
48
49     - github-packer-merge
50     - github-packer-verify
51
52 Macros
53 ======
54
55 lf-jenkins-cfg-global-vars
56 --------------------------
57
58 Manages the Global Jenkins variables. This macro will clear all exist macros
59 in Jenkins and replaces them with the ones defined by the
60 ci-management/jenkins-config/global-vars-SILO.sh script.
61
62 .. note::
63
64    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
65    config definitions for "production" and "sandbox" systems.
66
67 :Required parameters:
68
69     :jenkins-silos: Space separated list of Jenkins silos to update
70         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
71
72 lf-infra-jjbini
73 ---------------
74
75 Provides jenkins_jobs.ini configuration for Jenkins.
76
77 lf-infra-jjbini-sandbox
78 -----------------------
79
80 Provides jenkins_jobs.ini configuration for Jenkins sandbox.
81
82 .. todo:: This needs to be consolidated into lf-infra-jjbini when JJB 2.0 is available
83
84 lf-packer-verify-file-paths
85 ---------------------------
86
87 Gerrit file-paths for packer verify jobs.
88
89 lf-packer-file-paths
90 --------------------
91
92 Gerrit file-paths for packer jobs.
93
94 lf-packer-common
95 ----------------
96
97 Common packer configuration.
98
99 Job Templates
100 =============
101
102 Gerrit Branch Lock
103 ------------------
104
105 Job submits a patch to lock or unlock a project's branch.
106
107 :Template Names:
108     - {project-name}-gerrit-branch-lock-{stream}
109     - gerrit-branch-lock
110
111
112 Jenkins Configuration Merge
113 ---------------------------
114
115 Jenkins job to manage Global Jenkins configuration.
116
117 Global Environment Variables are managed via the
118 ``jenkins-config/global-vars-SILO.sh`` file in ci-management. Replace SILO with
119 the name of the Jenkins silo the variable configuration is for.
120
121 The format for this file is ``KEY=value`` for example::
122
123     GERRIT_URL=https://git.opendaylight.org/gerrit
124     GIT_BASE=git://devvexx.opendaylight.org/mirror/$PROJECT
125     GIT_URL=git://devvexx.opendaylight.org/mirror
126     JENKINS_HOSTNAME=vex-yul-odl-jenkins-2
127     LOGS_SERVER=https://logs.opendaylight.org
128     NEXUS_URL=https://nexus.opendaylight.org
129     ODLNEXUSPROXY=https://nexus.opendaylight.org
130     SILO=sandbox
131     SONAR_URL=https://sonar.opendaylight.org
132
133 .. note::
134
135    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
136    config definitions for "production" and "sandbox" systems.
137
138 :Template names:
139
140     - {project-name}-jenkins-cfg-merge
141     - gerrit-jenkins-cfg-merge
142     - github-jenkins-cfg-merge
143
144 :Optional parameters:
145
146     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
147     :jenkins-silos: Space separated list of Jenkins silos to update
148         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
149         (default: production sandbox)
150
151 Typically this template is automatically pulled in by the
152 "{project-name}-ci-jobs" job-group and does not need to be explicitly called if
153 the job group is being used.
154
155 Miniaml Example:
156
157 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-minimal.yaml
158    :language: yaml
159
160 Full Example:
161
162 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-full.yaml
163    :language: yaml
164
165
166 JJB Deploy Job
167 --------------
168
169 Deploy jobs to jenkins-sandbox system via code review comment
170
171 This job checks out the current code review patch and then runs a
172 `jenkins-jobs update` to push a patch defined by the comment.
173
174 :Template names:
175
176     - {project-name}-jjb-deploy-job
177     - gerrit-jjb-deploy-job
178     - github-jjb-deploy-job
179
180 :Comment Trigger: jjb-deploy JOB_NAME
181
182     .. note::
183
184        JOB_NAME can include the * wildcard character to push multiple jobs
185        matching the pattern. For example `jjb-deploy builder-jjb-*`` will push
186        all builder-jjb-* jobs to the sandbox system.
187
188 :Required parameters:
189
190     :build-node: The node to run build on.
191     :jenkins-ssh-credential: Credential to use for SSH. (Generally
192         should be configured in defaults.yaml)
193
194 :Optional parameters:
195
196     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
197     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
198
199
200 JJB Merge
201 ---------
202
203 Runs `jenkins-jobs update` to update production job configuration
204
205 :Template Names:
206     - {project-name}-jjb-merge
207     - gerrit-jjb-merge
208     - github-jjb-merge
209
210 :Required parameters:
211
212     :build-node: The node to run build on.
213     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
214         be configured in defaults.yaml)
215     :mvn-settings: The name of settings file containing credentials for
216         the project.
217
218 :Optional parameters:
219
220     :branch: Git branch to fetch for the build. (default: master)
221     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
222     :build-timeout: Timeout in seconds before aborting build. (default: 10)
223     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
224     :stream: Keyword that can be used to represent a release code-name.
225         Often the same as the branch. (default: master)
226     :submodule-recursive: Whether to checkout submodules recursively.
227         (default: true)
228
229     :gerrit_merge_triggers: Override Gerrit Triggers.
230     :gerrit_trigger_file_paths: Override file paths which can be used to
231         filter which file modifications will trigger a build.
232         (default defined by lf_jjb_common)
233
234
235 JJB Verify
236 ----------
237
238 Runs `jenkins-jobs test` to validate JJB syntax
239
240 :Template Names:
241     - {project-name}-jjb-verify
242     - gerrit-jjb-verify
243     - github-jjb-verify
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
251         the project.
252
253 :Optional parameters:
254
255     :branch: Git branch to fetch for the build. (default: master)
256     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
257     :build-timeout: Timeout in seconds before aborting build. (default: 10)
258     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
259     :stream: Keyword that can be used to represent a release code-name.
260         Often the same as the branch. (default: master)
261     :submodule-recursive: Whether to checkout submodules recursively.
262         (default: true)
263
264     :gerrit_verify_triggers: Override Gerrit Triggers.
265     :gerrit_trigger_file_paths: Override file paths which can be used to
266         filter which file modifications will trigger a build.
267         (default defined by lf_jjb_common)
268
269
270 Packer Merge
271 ------------
272
273 Packer Merge job runs `packer build` to build system images in the cloud.
274
275 :Template Names:
276     - {project-name}-packer-merge-{platforms}-{templates}
277     - gerrit-packer-merge
278     - github-packer-merge
279
280 :Required parameters:
281
282     :build-node: The node to run build on.
283     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
284         be configured in defaults.yaml)
285     :mvn-settings: The name of settings file containing credentials for
286         the project.
287     :platforms: Platform or distribution to build. Typically json file
288         found in the packer/vars directory. (Example: centos)
289     :template: System template to build. Typically shell script found in
290         the packer/provision directory. (Example: java-builder)
291
292 :Optional parameters:
293
294     :branch: Git branch to fetch for the build. (default: master)
295     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
296     :build-timeout: Timeout in seconds before aborting build. (default: 10)
297     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
298     :packer-cloud-settings: Name of settings file containing credentials
299         for the cloud that packer will build on. (default: packer-cloud-env)
300     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
301     :stream: Keyword that can be used to represent a release code-name.
302         Often the same as the branch. (default: master)
303     :submodule-recursive: Whether to checkout submodules recursively.
304         (default: true)
305
306     :gerrit_verify_triggers: Override Gerrit Triggers.
307
308
309 Packer Verify
310 -------------
311
312 Packer Verify job runs `packer validate` to verify packer configuration.
313
314 :Template Names:
315     - {project-name}-packer-verify
316     - gerrit-packer-verify
317     - github-packer-verify
318
319 :Required parameters:
320
321     :build-node: The node to run build on.
322     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
323         be configured in defaults.yaml)
324     :mvn-settings: The name of settings file containing credentials for
325         the project.
326
327 :Optional parameters:
328
329     :branch: Git branch to fetch for the build. (default: master)
330     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
331     :build-timeout: Timeout in seconds before aborting build. (default: 10)
332     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
333     :packer-cloud-settings: Name of settings file containing credentials
334         for the cloud that packer will build on. (default: packer-cloud-env)
335     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
336     :stream: Keyword that can be used to represent a release code-name.
337         Often the same as the branch. (default: master)
338     :submodule-recursive: Whether to checkout submodules recursively.
339         (default: true)
340
341     :gerrit_verify_triggers: Override Gerrit Triggers.
342     :gerrit_trigger_file_paths: Override file paths which can be used to
343         filter which file modifications will trigger a build.