docs/jjb/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-version: JJB version to install. (default: see job-template)
 428     :stream: Keyword that can be used to represent a release code-name.
 429         Often the same as the branch. (default: master)
 430     :submodule-recursive: Whether to checkout submodules recursively.
 431         (default: true)
 432     :submodule-timeout: Timeout (in minutes) for checkout operation.
 433         (default: 10)
 434
 435     :gerrit_merge_triggers: Override Gerrit Triggers.
 436     :gerrit_trigger_file_paths: Override file paths which can be used to
 437         filter which file modifications will trigger a build.
 438         (default defined by lf_jjb_common)
 439
 440
 441 .. _jjb-verify:
 442
 443 JJB Verify
 444 ----------
 445
 446 Runs `jenkins-jobs test` to validate JJB syntax
 447
 448 :Template Names:
 449     - {project-name}-jjb-verify
 450     - gerrit-jjb-verify
 451     - github-jjb-verify
 452
 453 :Comment Trigger: recheck|reverify
 454
 455 :Required parameters:
 456
 457     :build-node: The node to run build on.
 458     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 459         be configured in defaults.yaml)
 460
 461 :Optional parameters:
 462
 463     :branch: Git branch to fetch for the build. (default: master)
 464     :build-concurrent: Whether or not to allow this job to run multiple jobs
 465         simultaneously. (default: true)
 466     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 467     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 468     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 469     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 470     :jjb-version: JJB version to install. (default: see job-template)
 471     :stream: Keyword that can be used to represent a release code-name.
 472         Often the same as the branch. (default: master)
 473     :submodule-recursive: Whether to checkout submodules recursively.
 474         (default: true)
 475     :submodule-timeout: Timeout (in minutes) for checkout operation.
 476         (default: 10)
 477
 478     :gerrit_verify_triggers: Override Gerrit Triggers.
 479     :gerrit_trigger_file_paths: Override file paths which can be used to
 480         filter which file modifications will trigger a build.
 481         (default defined by lf_jjb_common)
 482
 483 .. _jjb-verify-upstream-gjjb:
 484
 485 JJB Verify Upstream Global JJB
 486 ------------------------------
 487
 488 Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
 489 patches. This job is useful to notify upstream that they may be breaking
 490 project level jobs.
 491
 492 :Template Names:
 493     - {project-name}-jjb-verify-upstream-gjjb
 494     - gerrit-jjb-verify-upstream-gjjb
 495
 496 :Comment Trigger: recheck|reverify
 497
 498 :Required parameters:
 499
 500     :build-node: The node to run build on.
 501     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 502         be configured in defaults.yaml)
 503
 504 :Optional parameters:
 505
 506     :branch: Git branch to fetch for the build. (default: master)
 507     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 508     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 509     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 510     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
 511     :jjb-version: JJB version to install. (default: see job-template)
 512     :stream: Keyword that can be used to represent a release code-name.
 513         Often the same as the branch. (default: master)
 514
 515 .. _info-yaml-verify:
 516
 517 Info YAML Verify
 518 ----------------
 519
 520 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 521 other file changes. Verifies INFO.yaml files follow the schema defined in
 522 `global-jjb/info-schema`.
 523
 524 :Template Names:
 525     - {project-name}-info-yaml-verify
 526     - gerrit-info-yaml-verify
 527     - github-info-yaml-verify
 528
 529 :Required parameters:
 530
 531     :build-node: The node to run build on.
 532     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 533         be configured in defaults.yaml)
 534
 535 :Optional parameters:
 536
 537     :branch: Git branch to fetch for the build. (default: master)
 538     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 539     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 540     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 541     :stream: Keyword that can be used to represent a release code-name.
 542         Often the same as the branch. (default: master)
 543     :submodule-recursive: Whether to checkout submodules recursively.
 544         (default: true)
 545     :submodule-timeout: Timeout (in minutes) for checkout operation.
 546         (default: 10)
 547
 548     :gerrit_verify_triggers: Override Gerrit Triggers.
 549
 550 .. _license-checker:
 551
 552 License Checker
 553 ---------------
 554
 555 Job to scan projects for files missing license headers.
 556
 557 :Template Names:
 558     - {project-name}-license-check
 559     - gerrit-license-check
 560     - github-license-check
 561
 562 :Optional parameters:
 563
 564     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 565     :file-patterns: Space-separated list of file patterns to scan.
 566         (default: \*.go \*.groovy \*.java \*.py \*.sh)
 567     :spdx-disable: Disable the SPDX-Identifier checker. (default: false)
 568     :lhc-version: Version of LHC to use. (default: 0.2.0)
 569     :license-exclude-paths: Comma-separated list of paths to exclude from the
 570         license checker. The paths used here will be matched using a contains
 571         rule so it is best to be as precise with the path as possible.
 572         For example a path of '/src/generated/' will be searched as
 573         '**/src/generated/**'.
 574         Example: org/opendaylight/yang/gen,protobuff/messages
 575         (default: '')
 576     :licenses-allowed: Comma-separated list of allowed licenses.
 577         (default: Apache-2.0,EPL-1.0,MIT)
 578     :project-pattern: The ANT based pattern for Gerrit Trigger to choose which
 579         projects to trigger job against. (default: '**')
 580
 581 .. _gjjb-openstack-cron:
 582
 583 OpenStack Cron
 584 --------------
 585
 586 Cron job that runs regularly to perform periodic tasks against OpenStack.
 587
 588 This job requires a Config File Provider file named ``clouds-yaml`` available
 589 containing the credentials for the cloud.
 590
 591 :Template Names:
 592     - {project-name}-openstack-cron
 593     - gerrit-openstack-cron
 594     - github-openstack-cron
 595
 596 :Required parameters:
 597
 598     :build-node: The node to run build on.
 599     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 600         be configured in defaults.yaml)
 601     :jenkins-urls: URLs to Jenkins systems to check for active builds.
 602
 603 :Optional parameters:
 604
 605     :branch: Git branch to fetch for the build. (default: master)
 606     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 607     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 608     :cron: Time when the packer image should be rebuilt (default: @hourly)
 609     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 610     :openstack-cloud: OS_CLOUD setting to pass to openstack client.
 611         (default: vex)
 612     :openstack-image-cleanup: Whether or not to run the image cleanup script.
 613         (default: true)
 614     :openstack-image-cleanup-age: Age in days of image before marking it for
 615         removal. (default: 30)
 616     :openstack-image-protect: Whether or not to run the image protect script.
 617         (default: true)
 618     :openstack-server-cleanup: Whether or not to run the server cleanup script.
 619         (default: true)
 620     :openstack-stack-cleanup: Whether or not to run the stack cleanup script.
 621         (default: true)
 622     :openstack-volume-cleanup: Whether or not to run the volume cleanup script.
 623         (default: true)
 624     :stream: Keyword that can be used to represent a release code-name.
 625         Often the same as the branch. (default: master)
 626     :submodule-recursive: Whether to checkout submodules recursively.
 627         (default: true)
 628     :submodule-timeout: Timeout (in minutes) for checkout operation.
 629         (default: 10)
 630
 631 Minimal Example:
 632
 633 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-minimal.yaml
 634
 635 Full Example:
 636
 637 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 638
 639
 640 .. _gjjb-packer-merge:
 641
 642 Packer Merge
 643 ------------
 644
 645 Packer Merge job runs `packer build` to build system images in the cloud.
 646
 647 :Template Names:
 648     - {project-name}-packer-merge-{platforms}-{templates}
 649     - gerrit-packer-merge
 650     - github-packer-merge
 651
 652 :Comment Trigger: remerge
 653
 654 :Required parameters:
 655
 656     :build-node: The node to run build on.
 657     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 658         be configured in defaults.yaml)
 659     :mvn-settings: The name of settings file containing credentials for
 660         the project.
 661     :platforms: Platform or distribution to build. Typically json file
 662         found in the packer/vars directory. (Example: centos)
 663     :template: System template to build. Typically shell script found in
 664         the packer/provision directory. (Example: java-builder)
 665
 666 :Optional parameters:
 667
 668     :cron: Time when the packer image should be rebuilt (default: @monthly)
 669     :branch: Git branch to fetch for the build. (default: master)
 670     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 671     :build-timeout: Timeout in minutes before aborting build. (default: 90)
 672     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 673     :openstack: Packer template uses an OpenStack builder (default: true).
 674     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 675         (default: vex).
 676     :packer-cloud-settings: Name of settings file containing credentials
 677         for the cloud that packer will build on. (default: packer-cloud-env)
 678     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 679     :stream: Keyword that can be used to represent a release code-name.
 680         Often the same as the branch. (default: master)
 681     :submodule-recursive: Whether to checkout submodules recursively.
 682         (default: true)
 683     :submodule-timeout: Timeout (in minutes) for checkout operation.
 684         (default: 10)
 685
 686     :gerrit_verify_triggers: Override Gerrit Triggers.
 687
 688 Test an in-progress patch
 689 ^^^^^^^^^^^^^^^^^^^^^^^^^
 690
 691 To test an in-progress patch from a GitHub Pull Request. Upload this
 692 job to the :doc:`Jenkins Sandbox <lfdocs:jenkins-sandbox>`. Then when manually
 693 building the job replace the GERRIT_REFSPEC parameter with the GitHub Pull
 694 Request number of the patch you would like to test.
 695
 696 Example GitHub:
 697
 698 .. code-block:: none
 699
 700    GERRIT_REFSPEC: origin/pr/49/merge
 701
 702 .. _gjjb-packer-verify:
 703
 704 Packer Verify
 705 -------------
 706
 707 Packer Verify job runs `packer validate` to verify packer configuration.
 708
 709 :Template Names:
 710     - {project-name}-packer-verify
 711     - gerrit-packer-verify
 712     - github-packer-verify
 713
 714 :Comment Trigger: recheck|reverify
 715
 716 :Required parameters:
 717
 718     :build-node: The node to run build on.
 719     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 720         be configured in defaults.yaml)
 721     :mvn-settings: The name of settings file containing credentials for
 722         the project.
 723
 724 :Optional parameters:
 725
 726     :branch: Git branch to fetch for the build. (default: master)
 727     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 728     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 729     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 730     :openstack: Packer template uses an OpenStack builder (default: true).
 731     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
 732         (default: vex).
 733     :packer-cloud-settings: Name of settings file containing credentials
 734         for the cloud that packer will build on. (default: packer-cloud-env)
 735     :packer-version: Version of packer to install / use in build. (default: 1.0.2)
 736     :stream: Keyword that can be used to represent a release code-name.
 737         Often the same as the branch. (default: master)
 738     :submodule-recursive: Whether to checkout submodules recursively.
 739         (default: true)
 740     :submodule-timeout: Timeout (in minutes) for checkout operation.
 741         (default: 10)
 742
 743     :gerrit_verify_triggers: Override Gerrit Triggers.
 744     :gerrit_trigger_file_paths: Override file paths which can be used to
 745         filter which file modifications will trigger a build.
 746
 747
 748 Puppet Verify
 749 -------------
 750
 751 Runs puppet-lint in the ``puppet-dir`` directory. puppet-lint runs recursively,
 752 the base directory is usually the best place to run from.
 753
 754 :Template Names:
 755
 756     - {project-name}-puppet-verify
 757     - gerrit-puppet-verify
 758     - github-puppet-verify
 759
 760 :Comment Trigger: recheck|reverify
 761
 762 :Required Parameters:
 763
 764     :build-node: The node to run build on.
 765     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 766         in defaults.yaml)
 767
 768 :Optional Parameters:
 769
 770     :branch: The branch to build against. (default: master)
 771     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 772     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 773     :gerrit_trigger_file_paths: Override file paths which used to filter which
 774         file modifications will trigger a build. Refer to JJB documentation for
 775         "file-path" details.
 776         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 777     :git-url: URL clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
 778     :puppet-dir: Directory containing the project's puppet module(s) relative
 779         to the workspace.
 780         (default: '')
 781     :puppet-lint-version: Version of puppet-lint to use for testing.
 782         (default: 2.3.6)
 783     :stream: Keyword representing a release code-name.
 784         Often the same as the branch. (default: master)
 785     :submodule-recursive: Whether to checkout submodules recursively.
 786         (default: true)
 787     :submodule-timeout: Timeout (in minutes) for checkout operation.
 788         (default: 10)