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