5ad9b6a31d24e8b5d93b36ab8a695963f28100e0
[releng/global-jjb.git] / lf-ci-jobs.rst
1 #######
2 CI Jobs
3 #######
4
5 Job Groups
6 ==========
7
8 .. include:: ../job-groups.rst
9
10 Below is a list of CI job groups:
11
12 .. literalinclude:: ../../jjb/lf-ci-job-groups.yaml
13    :language: yaml
14
15
16 Macros
17 ======
18
19 lf-infra-jjb-parameters
20 -----------------------
21
22 :Required Parameters:
23
24     :jjb-cache: Location of Jenkins Job Builder (JJB) cache used for jjb
25         jobs.
26     :jjb-version: Version of Jenkins Job Builder (JJB) to install and use in
27         the jjb jobs.
28
29 lf-jenkins-cfg-clouds
30 ---------------------
31
32 Deploys Jenkins Cloud configuration read from the ``jenkins-clouds`` directory
33 in ci-management repositories.
34
35 .. note::
36
37    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
38    config definitions for "production" and "sandbox" systems.
39
40 :Required Parameters:
41
42     :jenkins-silos: Space-separated list of Jenkins silos to update
43         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
44
45 lf-jenkins-cfg-global-vars
46 --------------------------
47
48 Manages the Global Jenkins variables. This macro will clear all exist macros
49 in Jenkins and replaces them with the ones defined by the
50 ci-management/jenkins-config/global-vars-SILO.sh script.
51
52 .. note::
53
54    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
55    config definitions for "production" and "sandbox" systems.
56
57 :Required parameters:
58
59     :jenkins-silos: Space-separated list of Jenkins silos to update
60         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
61
62 lf-infra-jjbini
63 ---------------
64
65 Provides jenkins_jobs.ini configuration for Jenkins.
66
67 lf-infra-jjbini-sandbox
68 -----------------------
69
70 Provides jenkins_jobs.ini configuration for Jenkins sandbox.
71
72 .. todo:: This needs to be consolidated into lf-infra-jjbini when JJB 2.0 is available
73
74 lf-packer-common
75 ----------------
76
77 Common packer configuration.
78
79 lf-packer-file-paths
80 --------------------
81
82 Gerrit file-paths for packer jobs.
83
84 lf-packer-parameters
85 --------------------
86
87 Parameters useful for packer related tasks.
88
89 :Parameters:
90
91     :packer-version: Version of packer to install / use.
92         (shell: PACKER_VERSION)
93
94 lf-packer-verify-file-paths
95 ---------------------------
96
97 Gerrit file-paths for packer verify jobs.
98
99 lf-puppet-parameters
100 --------------------
101
102 Parameters useful for Puppet related tasks.
103
104 :Parameters:
105
106     :puppet-lint-version: Version of puppet-lint to install / use.
107         (shell: PUPPET_LINT_VERSION)
108
109 Job Templates
110 =============
111
112 .. _gerrit-branch-lock:
113
114 Gerrit Branch Lock
115 ------------------
116
117 Job submits a patch to lock or unlock a project's branch.
118
119 :Template Names:
120     - {project-name}-gerrit-branch-lock-{stream}
121     - gerrit-branch-lock
122
123 :Comment Trigger:
124
125     * lock branch
126     * unlock branch
127
128 :Required parameters:
129
130     :build-node: The node to run build on.
131     :jenkins-ssh-credential: Credential to use for SSH. (Generally
132         should be configured in defaults.yaml)
133
134 :Optional parameters:
135
136     :branch: Git branch to build against. (default: master)
137     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
138     :stream: Keyword that can be used to represent a release code-name.
139         Often the same as the branch. (default: master)
140     :submodule-timeout: Timeout (in minutes) for checkout operation.
141         (default: 10)
142     :gerrit_merge_triggers: Override Gerrit Triggers.
143
144 .. _lf-global-jjb-jenkins-cfg-merge:
145
146 Jenkins Configuration Merge
147 ---------------------------
148
149 Jenkins job to manage Global Jenkins configuration.
150
151 .. note::
152
153    Requires the jjbini file in Jenkins CFP to contain JJB 2.0 style
154    config definitions for "production" and "sandbox" systems.
155
156 :Template names:
157
158     - {project-name}-jenkins-cfg-merge
159     - gerrit-jenkins-cfg-merge
160     - github-jenkins-cfg-merge
161
162 :Optional parameters:
163
164     :branch: Git branch to build against. (default: master)
165     :cron: How often to run the job on a cron schedule. (default: @daily)
166     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
167     :jenkins-silos: Space separated list of Jenkins silos to update
168         configuration for as defined in ~/.config/jenkins_jobs/jenkins_jobs.ini
169         (default: production sandbox)
170
171 Typically this template is automatically pulled in by the
172 "{project-name}-ci-jobs" job-group and does not need to be explicitly called if
173 the job group is being used.
174
175 Minimal Example:
176
177 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-minimal.yaml
178    :language: yaml
179
180 Full Example:
181
182 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-merge-full.yaml
183    :language: yaml
184
185 .. _jenkins-cfg-envvar:
186
187 Global Environment Variables
188 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189
190 Global Environment Variables are managed via the
191 ``jenkins-config/global-vars-SILO.sh`` file in ci-management. Replace SILO with
192 the name of the Jenkins silo the variable configuration is for.
193
194 The format for this file is ``KEY=value`` for example::
195
196     GERRIT_URL=https://git.opendaylight.org/gerrit
197     GIT_BASE=git://devvexx.opendaylight.org/mirror/$PROJECT
198     GIT_URL=git://devvexx.opendaylight.org/mirror
199     JENKINS_HOSTNAME=vex-yul-odl-jenkins-2
200     LOGS_SERVER=https://logs.opendaylight.org
201     NEXUS_URL=https://nexus.opendaylight.org
202     ODLNEXUSPROXY=https://nexus.opendaylight.org
203     SILO=sandbox
204     SONAR_URL=https://sonar.opendaylight.org
205
206 Cloud Configuration
207 ^^^^^^^^^^^^^^^^^^^
208
209 This configuration requires the OpenStack Cloud plugin in Jenkins and is
210 currently the only cloud plugin supported.
211
212 OpenStack Cloud plugin version supported:
213
214 * 2.30 - 2.34
215 * 2.35 - 2.37
216
217 Cloud configuration are managed via a directory structure in ci-management as
218 follows:
219
220 - jenkins-config/clouds/openstack/
221 - jenkins-config/clouds/openstack/cattle/cloud.cfg
222 - jenkins-config/clouds/openstack/cattle/centos7-builder-2c-2g.cfg
223 - jenkins-config/clouds/openstack/cattle/centos7-builder-4c-4g.cfg
224 - jenkins-config/clouds/openstack/cattle/centos7-docker-4c-4g.cfg
225
226 The directory name inside of the "openstack" directory is used as the name of
227 the cloud configuration. In this case "cattle" is being used as the cloud name.
228
229 The ``cloud.cfg`` file is a special file used to configure the main cloud
230 configuration in the format ``KEY=value``.
231
232 :Cloud Parameters:
233
234     :CLOUD_URL: API endpoint URL for Keystone.
235         (default: "")
236     :CLOUD_IGNORE_SSL: Ignore unverified SSL certificates. (default: false)
237     :CLOUD_ZONE: OpenStack region to use. (default: "")
238     :CLOUD_CREDENTIAL_ID: Credential to use for authentication to OpenStack.
239         (default: "os-cloud")
240     :INSTANCE_CAP: Total number of instances the cloud will allow spin up.
241         (default: null)
242     :SANDBOX_CAP: Total number of instances the cloud will allow to
243         spin up. This applies to "sandbox" systems and overrides the
244         INSTANCE_CAP setting. (default: null)
245
246 :Template Parameters:
247
248     .. note::
249
250        In the case of template definitions of a parameter below is not passed
251        the one defined in default clouds will be inherited.
252
253     :IMAGE_NAME: The image name to use for this template.
254         (required)
255     :HARDWARE_ID: OpenStack flavor to use. (required)
256
257     :LABELS: Labels to assign to the vm. (default: FILE_NAME)
258     :NETWORK_ID: OpenStack network to use. (default: "")
259     :USER_DATA_ID: User Data to pass into the instance.
260         (default: jenkins-init-script)
261     :INSTANCE_CAP: Total number of instances of this type that can be launched
262         at one time. When defined in clouds.cfg it defines the total for the
263         entire cloud. (default: null)
264     :SANDBOX_CAP: Total number of instances of this type that can be launched
265         at one time. When defined in clouds.cfg it defines the total for the
266         entire cloud. This applies to "sandbox" systems and overrides the
267         INSTANCE_CAP setting. (default: null)
268     :FLOATING_IP_POOL: Floating ip pool to use. (default: "")
269     :SECURITY_GROUPS: Security group to use. (default: "default")
270     :AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
271     :START_TIMEOUT: Number of milliseconds to wait for the agent to be
272         provisioned and connected. (default: 600000)
273     :KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
274         (default: jenkins)
275     :NUM_EXECUTORS: Number of executors to enable for the instance.
276         (default: 1)
277     :JVM_OPTIONS: JVM Options to pass to Java. (default: "")
278     :FS_ROOT: File system root for the workspace. (default: "/w")
279     :RETENTION_TIME: Number of minutes to wait for an idle slave to be used
280         again before it's removed. If set to -1, the slave will be kept
281         forever. (default: 0)
282     :CONNECTION_TYPE: The connection type for Jenkins to connect to the build
283         minion. Valid options: JNLP, SSH. (default: "SSH")
284
285 For a live example see the OpenDaylight project jenkins-config directory.
286 https://github.com/opendaylight/releng-builder/tree/master/jenkins-config
287
288 Troubleshooting
289 ^^^^^^^^^^^^^^^
290
291 :Cloud Configuration:
292
293     The directory ``groovy-inserts`` contains the groovy script output that is
294     used to push to Jenkins. In the event of a job failure this file can be
295     inspected.
296
297  .. _lf-global-jjb-jenkins-cfg-verify:
298
299 Jenkins Configuration Verify
300 ----------------------------
301
302 Jenkins job to verify the Global Jenkins configuration.
303
304 Requires the ``clouds-yaml`` file to be setup on the Jenkins host.
305
306 :Template names:
307
308     - {project-name}-jenkins-cfg-verify
309     - gerrit-jenkins-cfg-verify
310     - github-jenkins-cfg-verify
311
312 :Optional parameters:
313
314     :branch: Git branch to build against. (default: master)
315     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
316
317 This job is not part of the "{project-name}-ci-jobs" group. It must be called
318 explicitly.
319
320 Example:
321
322 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/jenkins-cfg-verify.yaml
323    :language: yaml
324
325
326 .. _jenkins-sandbox-cleanup:
327
328 Jenkins Sandbox Cleanup
329 -----------------------
330
331 Cleanup Jenkins Sandbox of jobs and views periodically.
332
333 :Template names:
334
335     - {project-name}-jenkins-sandbox-cleanup
336     - gerrit-jenkins-sandbox-cleanup
337     - github-jenkins-sandbox-cleanup
338
339 :Comment Trigger: NONE
340
341 :Required parameters:
342
343     :build-node: The node to run build on.
344     :jenkins-ssh-credential: Credential to use for SSH. (Generally
345         should be configured in defaults.yaml)
346
347 :Optional parameters:
348
349     :cron: Schedule to run job. (default: '0 8 * * 6')
350
351
352 .. _jjb-deploy:
353
354 JJB Deploy Job
355 --------------
356
357 Deploy jobs to jenkins-sandbox system via code review comment.
358
359 This job checks out the current code review patch and then runs a
360 ``jenkins-jobs update`` to push a patch defined by the comment.
361
362 :Template names:
363
364     - {project-name}-jjb-deploy-job
365     - gerrit-jjb-deploy-job
366     - github-jjb-deploy-job
367
368 :Comment Trigger: jjb-deploy JOB_NAME
369
370     .. note::
371
372        The JJB Deploy Job is configured to trigger only if the Gerrit comment
373        starts with the `jjb-deploy` keyword.
374
375        Example of a valid command in Gerrit comment that triggers the job:
376
377        ``jjb-deploy builder-jjb-*``
378
379        Example of a invalid command in Gerrit comment that would _not_ trigger
380        the job:
381
382        ``Update the job. jjb-deploy builder-jjb-*``
383
384        JOB_NAME can include the * wildcard character to push multiple jobs
385        matching the pattern. For example ``jjb-deploy builder-jjb-*`` will push
386        all builder-jjb-* jobs to the sandbox system.
387
388 :Required parameters:
389
390     :build-node: The node to run build on.
391     :jenkins-ssh-credential: Credential to use for SSH. (Generally
392         should be configured in defaults.yaml)
393
394 :Optional parameters:
395
396     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
397     :gerrit_jjb_deploy_job_triggers: Override Gerrit Triggers.
398
399
400 .. _jjb-merge:
401
402 JJB Merge
403 ---------
404
405 Runs `jenkins-jobs update` to update production job configuration
406
407 :Template Names:
408     - {project-name}-jjb-merge
409     - gerrit-jjb-merge
410     - github-jjb-merge
411
412 :Comment Trigger: remerge
413
414 :Required parameters:
415
416     :build-node: The node to run build on.
417     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
418         be configured in defaults.yaml)
419
420 :Optional parameters:
421
422     :branch: Git branch to fetch for the build. (default: master)
423     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
424     :build-timeout: Timeout in minutes before aborting build. (default: 10)
425     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
426     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
427     :jjb-workers: Number of threads to run **update** with. Set to 0 by default
428         which is equivalent to the number of available CPU cores. (default: 0)
429     :jjb-version: JJB version to install. (default: see job-template)
430     :stream: Keyword that can be used to represent a release code-name.
431         Often the same as the branch. (default: master)
432     :submodule-recursive: Whether to checkout submodules recursively.
433         (default: true)
434     :submodule-timeout: Timeout (in minutes) for checkout operation.
435         (default: 10)
436
437     :gerrit_merge_triggers: Override Gerrit Triggers.
438     :gerrit_trigger_file_paths: Override file paths which can be used to
439         filter which file modifications will trigger a build.
440         (default defined by lf_jjb_common)
441
442
443 .. _jjb-verify:
444
445 JJB Verify
446 ----------
447
448 Runs `jenkins-jobs test` to validate JJB syntax
449
450 :Template Names:
451     - {project-name}-jjb-verify
452     - gerrit-jjb-verify
453     - github-jjb-verify
454
455 :Comment Trigger: recheck|reverify
456
457 :Required parameters:
458
459     :build-node: The node to run build on.
460     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
461         be configured in defaults.yaml)
462
463 :Optional parameters:
464
465     :branch: Git branch to fetch for the build. (default: master)
466     :build-concurrent: Whether or not to allow this job to run multiple jobs
467         simultaneously. (default: true)
468     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
469     :build-timeout: Timeout in minutes before aborting build. (default: 10)
470     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
471     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
472     :jjb-version: JJB version to install. (default: see job-template)
473     :stream: Keyword that can be used to represent a release code-name.
474         Often the same as the branch. (default: master)
475     :submodule-recursive: Whether to checkout submodules recursively.
476         (default: true)
477     :submodule-timeout: Timeout (in minutes) for checkout operation.
478         (default: 10)
479     :throttle_categories: List of categories to throttle by.
480     :throttle-enabled: Whether or not to enable throttling on the job.
481         (default: true)
482     :throttle-max-per-node: Max jobs to run on the same node. (default: 1)
483     :throttle-max-total: Max jobs to run across the entire project. - 0
484         means 'unlimited' (default: 0)
485     :throttle-option: Throttle by the project or by list of categories
486         defined in the throttle plugin configuration. (options: 'project',
487         'category'; default: project)
488
489     :gerrit_verify_triggers: Override Gerrit Triggers.
490     :gerrit_trigger_file_paths: Override file paths which can be used to
491         filter which file modifications will trigger a build.
492         (default defined by lf_jjb_common)
493
494 .. _jjb-verify-upstream-gjjb:
495
496 JJB Verify Upstream Global JJB
497 ------------------------------
498
499 Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
500 patches. This job is useful to notify upstream that they may be breaking
501 project level jobs.
502
503 :Template Names:
504     - {project-name}-jjb-verify-upstream-gjjb
505     - gerrit-jjb-verify-upstream-gjjb
506
507 :Comment Trigger: recheck|reverify
508
509 :Required parameters:
510
511     :build-node: The node to run build on.
512     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
513         be configured in defaults.yaml)
514
515 :Optional parameters:
516
517     :branch: Git branch to fetch for the build. (default: master)
518     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
519     :build-timeout: Timeout in minutes before aborting build. (default: 10)
520     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
521     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
522     :jjb-version: JJB version to install. (default: see job-template)
523     :stream: Keyword that can be used to represent a release code-name.
524         Often the same as the branch. (default: master)
525
526 .. _info-yaml-verify:
527
528 Info YAML Verify
529 ----------------
530
531 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
532 other file changes. Verifies INFO.yaml files follow the schema defined in
533 `global-jjb/info-schema`.
534
535 :Template Names:
536     - {project-name}-info-yaml-verify
537     - gerrit-info-yaml-verify
538     - github-info-yaml-verify
539
540 :Required parameters:
541
542     :build-node: The node to run build on.
543     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
544         be configured in defaults.yaml)
545
546 :Optional parameters:
547
548     :branch: Git branch to fetch for the build. (default: master)
549     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
550     :build-timeout: Timeout in minutes before aborting build. (default: 10)
551     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
552     :stream: Keyword that can be used to represent a release code-name.
553         Often the same as the branch. (default: master)
554     :submodule-recursive: Whether to checkout submodules recursively.
555         (default: true)
556     :submodule-timeout: Timeout (in minutes) for checkout operation.
557         (default: 10)
558
559     :gerrit_verify_triggers: Override Gerrit Triggers.
560
561 .. _license-checker:
562
563 License Checker
564 ---------------
565
566 Job to scan projects for files missing license headers.
567
568 :Template Names:
569     - {project-name}-license-check
570     - gerrit-license-check
571     - github-license-check
572
573 :Optional parameters:
574
575     :build-timeout: Timeout in minutes before aborting build. (default: 15)
576     :file-patterns: Space-separated list of file patterns to scan.
577         (default: \*.go \*.groovy \*.java \*.py \*.sh)
578     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
579     :lhc-version: Version of LHC to use. (default: 0.2.0)
580     :license-exclude-paths: Comma-separated list of paths to exclude from the
581         license checker. The paths used here will be matched using a contains
582         rule so it is best to be as precise with the path as possible.
583         For example a path of '/src/generated/' will be searched as
584         '**/src/generated/**'.
585         Example: org/opendaylight/yang/gen,protobuff/messages
586         (default: '')
587     :licenses-allowed: Comma-separated list of allowed licenses.
588         (default: Apache-2.0,EPL-1.0,MIT)
589     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
590         projects to trigger job against. (default: '**')
591
592 .. _gjjb-openstack-cron:
593
594 OpenStack Cron
595 --------------
596
597 Cron job that runs regularly to perform periodic tasks against OpenStack.
598
599 This job requires a Config File Provider file named ``clouds-yaml`` available
600 containing the credentials for the cloud.
601
602 :Template Names:
603     - {project-name}-openstack-cron
604     - gerrit-openstack-cron
605     - github-openstack-cron
606
607 :Required parameters:
608
609     :build-node: The node to run build on.
610     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
611         be configured in defaults.yaml)
612     :jenkins-urls: URLs to Jenkins systems to check for active builds.
613
614 :Optional parameters:
615
616     :branch: Git branch to fetch for the build. (default: master)
617     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
618     :build-timeout: Timeout in minutes before aborting build. (default: 90)
619     :cron: Time when the packer image should be rebuilt (default: @hourly)
620     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
621     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
622         (default: vex)
623     :openstack-image-cleanup: Whether or not to run the image cleanup script.
624         (default: true)
625     :openstack-image-cleanup-age: Age in days of image before marking it for
626         removal. (default: 30)
627     :openstack-image-protect: Whether or not to run the image protect script.
628         (default: true)
629     :openstack-server-cleanup: Whether or not to run the server cleanup script.
630         (default: true)
631     :openstack-stack-cleanup: Whether or not to run the stack cleanup script.
632         (default: true)
633     :openstack-volume-cleanup: Whether or not to run the volume cleanup script.
634         (default: true)
635     :stream: Keyword that can be used to represent a release code-name.
636         Often the same as the branch. (default: master)
637     :submodule-recursive: Whether to checkout submodules recursively.
638         (default: true)
639     :submodule-timeout: Timeout (in minutes) for checkout operation.
640         (default: 10)
641
642 Minimal Example:
643
644 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-minimal.yaml
645
646 Full Example:
647
648 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
649
650
651 .. _gjjb-packer-merge:
652
653 Packer Merge
654 ------------
655
656 Packer Merge job runs `packer build` to build system images in the cloud.
657
658 :Template Names:
659     - {project-name}-packer-merge-{platforms}-{templates}
660     - gerrit-packer-merge
661     - github-packer-merge
662
663 :Comment Trigger: remerge
664
665 :Required parameters:
666
667     :build-node: The node to run build on.
668     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
669         be configured in defaults.yaml)
670     :mvn-settings: The name of settings file containing credentials for
671         the project.
672     :platforms: Platform or distribution to build. Typically json file
673         found in the packer/vars directory. (Example: centos)
674     :template: System template to build. Typically shell script found in
675         the packer/provision directory. (Example: java-builder)
676
677 :Optional parameters:
678
679     :cron: Time when the packer image should be rebuilt (default: @monthly)
680     :branch: Git branch to fetch for the build. (default: master)
681     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
682     :build-timeout: Timeout in minutes before aborting build. (default: 90)
683     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
684     :openstack: Packer template uses an OpenStack builder (default: true).
685     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
686         (default: vex).
687     :packer-cloud-settings: Name of settings file containing credentials
688         for the cloud that packer will build on. (default: packer-cloud-env)
689     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
690     :stream: Keyword that can be used to represent a release code-name.
691         Often the same as the branch. (default: master)
692     :submodule-recursive: Whether to checkout submodules recursively.
693         (default: true)
694     :submodule-timeout: Timeout (in minutes) for checkout operation.
695         (default: 10)
696
697     :gerrit_verify_triggers: Override Gerrit Triggers.
698
699 Test an in-progress patch
700 ^^^^^^^^^^^^^^^^^^^^^^^^^
701
702 To test an in-progress patch from a GitHub Pull Request. Upload this
703 job to the :doc:`Jenkins Sandbox <lfdocs:jenkins-sandbox>`. Then when manually
704 building the job replace the GERRIT_REFSPEC parameter with the GitHub Pull
705 Request number of the patch you would like to test.
706
707 Example GitHub:
708
709 .. code-block:: none
710
711    GERRIT_REFSPEC: origin/pr/49/merge
712
713 .. _gjjb-packer-verify:
714
715 Packer Verify
716 -------------
717
718 Packer Verify job runs `packer validate` to verify packer configuration.
719
720 :Template Names:
721     - {project-name}-packer-verify
722     - gerrit-packer-verify
723     - github-packer-verify
724
725 :Comment Trigger: recheck|reverify
726
727 :Required parameters:
728
729     :build-node: The node to run build on.
730     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
731         be configured in defaults.yaml)
732     :mvn-settings: The name of settings file containing credentials for
733         the project.
734
735 :Optional parameters:
736
737     :branch: Git branch to fetch for the build. (default: master)
738     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
739     :build-timeout: Timeout in minutes before aborting build. (default: 10)
740     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
741     :openstack: Packer template uses an OpenStack builder (default: true).
742     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
743         (default: vex).
744     :packer-cloud-settings: Name of settings file containing credentials
745         for the cloud that packer will build on. (default: packer-cloud-env)
746     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
747     :stream: Keyword that can be used to represent a release code-name.
748         Often the same as the branch. (default: master)
749     :submodule-recursive: Whether to checkout submodules recursively.
750         (default: true)
751     :submodule-timeout: Timeout (in minutes) for checkout operation.
752         (default: 10)
753
754     :gerrit_verify_triggers: Override Gerrit Triggers.
755     :gerrit_trigger_file_paths: Override file paths which can be used to
756         filter which file modifications will trigger a build.
757
758
759 Puppet Verify
760 -------------
761
762 Runs puppet-lint in the ``puppet-dir`` directory. puppet-lint runs recursively,
763 the base directory is usually the best place to run from.
764
765 :Template Names:
766
767     - {project-name}-puppet-verify
768     - gerrit-puppet-verify
769     - github-puppet-verify
770
771 :Comment Trigger: recheck|reverify
772
773 :Required Parameters:
774
775     :build-node: The node to run build on.
776     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
777         in defaults.yaml)
778
779 :Optional Parameters:
780
781     :branch: The branch to build against. (default: master)
782     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
783     :build-timeout: Timeout in minutes before aborting build. (default: 15)
784     :gerrit_trigger_file_paths: Override file paths which used to filter which
785         file modifications will trigger a build. Refer to JJB documentation for
786         "file-path" details.
787         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
788     :git-url: URL clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
789     :puppet-dir: Directory containing the project's puppet module(s) relative
790         to the workspace.
791         (default: '')
792     :puppet-lint-version: Version of puppet-lint to use for testing.
793         (default: 2.3.6)
794     :stream: Keyword representing a release code-name.
795         Often the same as the branch. (default: master)
796     :submodule-recursive: Whether to checkout submodules recursively.
797         (default: true)
798     :submodule-timeout: Timeout (in minutes) for checkout operation.
799         (default: 10)