Migrate Global JJB docs to RST
[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-jjb-deploy-job
16     - gerrit-jjb-merge
17     - gerrit-jjb-verify
18
19 {project-name}-github-ci-jobs
20 -----------------------------
21
22 Recommended jobs that should be deployed CI using GitHub.
23
24 :Includes:
25
26     - github-jjb-deploy-job
27     - github-jjb-merge
28     - github-jjb-verify
29
30 {project-name}-packer-jobs
31 --------------------------
32
33 Jobs related to Packer builds for CI using Gerrit.
34
35 :Includes:
36
37     - gerrit-packer-merge
38     - gerrit-packer-verify
39
40 {project-name}-github-packer-jobs
41 ---------------------------------
42
43 Jobs related to Packer builds for CI using GitHub.
44
45 :Includes:
46
47     - github-packer-merge
48     - github-packer-verify
49
50 Macros
51 ======
52
53 lf-infra-jjbini
54 ---------------
55
56 Provides jenkins_jobs.ini configuration for Jenkins.
57
58 lf-infra-jjbini-sandbox
59 -----------------------
60
61 Provides jenkins_jobs.ini configuration for Jenkins sandbox.
62
63 .. todo:: This needs to be consolidated into lf-infra-jjbini when JJB 2.0 is available
64
65 lf-packer-verify-file-paths
66 ---------------------------
67
68 Gerrit file-paths for packer verify jobs.
69
70 lf-packer-file-paths
71 --------------------
72
73 Gerrit file-paths for packer jobs.
74
75 lf-packer-common
76 ----------------
77
78 Common packer configuration.
79
80 Job Templates
81 =============
82
83 Gerrit Branch Lock
84 ------------------
85
86 Job submits a patch to lock or unlock a project's branch.
87
88 :Template Names:
89     - {project-name}-gerrit-branch-lock-{stream}
90     - gerrit-branch-lock
91
92
93 JJB Deploy Job
94 --------------
95
96 Deploy jobs to jenkins-sandbox system via code review comment
97
98 This job checks out the current code review patch and then runs a
99 `jenkins-jobs update` to push a patch defined by the comment.
100
101 :Template names:
102
103     - {project-name}-jjb-deploy-job
104     - gerrit-jjb-deploy-job
105     - github-jjb-deploy-job
106
107 :Comment Trigger: jjb-deploy JOB_NAME
108
109     .. note::
110
111        JOB_NAME can include the * wildcard character to push multiple jobs
112        matching the pattern. For example `jjb-deploy builder-jjb-*`` will push
113        all builder-jjb-* jobs to the sandbox system.
114
115 :Required parameters:
116
117     :build-node: The node to run build on.
118     :jenkins-ssh-credential: Credential to use for SSH. (Generally
119         should be configured in defaults.yaml)
120
121 :Optional parameters:
122
123     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
124     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
125
126
127 JJB Merge
128 ---------
129
130 Runs `jenkins-jobs update` to update production job configuration
131
132 :Template Names:
133     - {project-name}-jjb-merge
134     - gerrit-jjb-merge
135     - github-jjb-merge
136
137 :Required parameters:
138
139     :build-node: The node to run build on.
140     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
141         be configured in defaults.yaml)
142     :mvn-settings: The name of settings file containing credentials for
143         the project.
144
145 :Optional parameters:
146
147     :branch: Git branch to fetch for the build. (default: master)
148     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
149     :build-timeout: Timeout in seconds before aborting build. (default: 10)
150     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
151     :stream: Keyword that can be used to represent a release code-name.
152         Often the same as the branch. (default: master)
153     :submodule-recursive: Whether to checkout submodules recursively.
154         (default: true)
155
156     :gerrit_merge_triggers: Override Gerrit Triggers.
157     :gerrit_trigger_file_paths: Override file paths which can be used to
158         filter which file modifications will trigger a build.
159         (default defined by lf_jjb_common)
160
161
162 JJB Verify
163 ----------
164
165 Runs `jenkins-jobs test` to validate JJB syntax
166
167 :Template Names:
168     - {project-name}-jjb-verify
169     - gerrit-jjb-verify
170     - github-jjb-verify
171
172 :Required parameters:
173
174     :build-node: The node to run build on.
175     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
176         be configured in defaults.yaml)
177     :mvn-settings: The name of settings file containing credentials for
178         the project.
179
180 :Optional parameters:
181
182     :branch: Git branch to fetch for the build. (default: master)
183     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
184     :build-timeout: Timeout in seconds before aborting build. (default: 10)
185     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
186     :stream: Keyword that can be used to represent a release code-name.
187         Often the same as the branch. (default: master)
188     :submodule-recursive: Whether to checkout submodules recursively.
189         (default: true)
190
191     :gerrit_verify_triggers: Override Gerrit Triggers.
192     :gerrit_trigger_file_paths: Override file paths which can be used to
193         filter which file modifications will trigger a build.
194         (default defined by lf_jjb_common)
195
196
197 Packer Merge
198 ------------
199
200 Packer Merge job runs `packer build` to build system images in the cloud.
201
202 :Template Names:
203     - {project-name}-packer-merge-{platforms}-{templates}
204     - gerrit-packer-merge
205     - github-packer-merge
206
207 :Required parameters:
208
209     :build-node: The node to run build on.
210     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
211         be configured in defaults.yaml)
212     :mvn-settings: The name of settings file containing credentials for
213         the project.
214     :platforms: Platform or distribution to build. Typically json file
215         found in the packer/vars directory. (Example: centos)
216     :template: System template to build. Typically shell script found in
217         the packer/provision directory. (Example: java-builder)
218
219 :Optional parameters:
220
221     :branch: Git branch to fetch for the build. (default: master)
222     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
223     :build-timeout: Timeout in seconds before aborting build. (default: 10)
224     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
225     :packer-cloud-settings: Name of settings file containing credentials
226         for the cloud that packer will build on. (default: packer-cloud-env)
227     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
228     :stream: Keyword that can be used to represent a release code-name.
229         Often the same as the branch. (default: master)
230     :submodule-recursive: Whether to checkout submodules recursively.
231         (default: true)
232
233     :gerrit_verify_triggers: Override Gerrit Triggers.
234
235
236 Packer Verify
237 -------------
238
239 Packer Verify job runs `packer validate` to verify packer configuration.
240
241 :Template Names:
242     - {project-name}-packer-verify
243     - gerrit-packer-verify
244     - github-packer-verify
245
246 :Required parameters:
247
248     :build-node: The node to run build on.
249     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
250         be configured in defaults.yaml)
251     :mvn-settings: The name of settings file containing credentials for
252         the project.
253
254 :Optional parameters:
255
256     :branch: Git branch to fetch for the build. (default: master)
257     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
258     :build-timeout: Timeout in seconds before aborting build. (default: 10)
259     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
260     :packer-cloud-settings: Name of settings file containing credentials
261         for the cloud that packer will build on. (default: packer-cloud-env)
262     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
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_verify_triggers: Override Gerrit Triggers.
269     :gerrit_trigger_file_paths: Override file paths which can be used to
270         filter which file modifications will trigger a build.