docs/jjb/lf-maven-jobs.rst

   1 ##########
   2 Maven Jobs
   3 ##########
   4
   5 Job Groups
   6 ==========
   7
   8 .. include:: ../job-groups.rst
   9
  10 Below is a list of Maven job groups:
  11
  12 .. literalinclude:: ../../jjb/lf-maven-job-groups.yaml
  13    :language: yaml
  14
  15
  16 Macros
  17 ======
  18
  19 lf-infra-maven-sonar
  20 --------------------
  21
  22 Runs Sonar against a Maven project.
  23
  24 :Required Parameters:
  25
  26     :java-version: Version of Java to execute Sonar with.
  27     :mvn-version: Version of Maven to execute Sonar with.
  28     :mvn-settings: Maven settings.xml file containing credentials to use.
  29
  30 lf-infra-maven-sonarcloud
  31 -------------------------
  32
  33 Runs Sonar against a Maven project and pushes results to SonarCloud.
  34
  35 :Required Parameters:
  36
  37     :java-version: Version of Java to execute Sonar with.
  38     :mvn-version: Version of Maven to execute Sonar with.
  39     :mvn-settings: Maven settings.xml file containing credentials to use.
  40     :sonarcloud-project-key: SonarCloud project key.
  41     :sonarcloud-project-organization: SonarCloud project organization.
  42     :sonarcloud-api-token: SonarCloud API Token.
  43
  44 lf-maven-build
  45 --------------
  46
  47 Calls the maven build script to perform a maven build.
  48
  49 :Required parameters:
  50
  51     :mvn-goals: The maven goals to perform for the build.
  52         (default: clean deploy)
  53
  54 lf-maven-common
  55 ---------------
  56
  57 Common Jenkins configuration for Maven jobs.
  58
  59 lf-maven-deploy
  60 ---------------
  61
  62 Calls the maven deploy script to push artifacts to Nexus.
  63
  64 lf-maven-versions-plugin
  65 ------------------------
  66
  67 Conditionally calls Maven versions plugin to set, update and commit the maven `versions:set`.
  68
  69 :Required Parameters:
  70
  71     :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
  72     :mvn-version: Version of Maven to execute Sonar with.
  73     :mvn-pom: Location of pom.xml.
  74     :maven-versions-plugin-set-version: Version number to upgrade to.
  75     :mvn-settings: Maven settings.xml file containing credentials to use.
  76
  77 lf-maven-stage
  78 --------------
  79
  80 Calls the maven stage script to push artifacts to a Nexus staging repository.
  81
  82 :Required Parameters:
  83
  84     :mvn-global-settings: The name of the Maven global settings to use for
  85         Maven configuration.
  86     :mvn-settings: The name of settings file containing credentials for the project.
  87
  88 lf-update-java-alternatives
  89 ---------------------------
  90
  91 Setup Java alternatives for the Distro.
  92
  93 :Required Parameters:
  94
  95     :java-version: Version of Java to set as the default Java.
  96         Eg. openjdk8
  97
  98 Job Templates
  99 =============
 100
 101 Maven CLM
 102 ---------
 103
 104 Produces a CLM scan of the code into Nexus IQ Server.
 105
 106 :Template Names:
 107
 108     - {project-name}-maven-clm-{stream}
 109     - gerrit-maven-clm
 110     - github-maven-clm
 111
 112 :Comment Trigger: run-clm
 113
 114 :Required parameters:
 115
 116     :build-node:    The node to run build on.
 117     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 118         be configured in defaults.yaml)
 119     :mvn-settings: The name of settings file containing credentials for the project.
 120
 121 :Optional parameters:
 122
 123     :branch: The branch to build against. (default: master)
 124     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 125     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 126     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 127     :java-version: Version of Java to use for the build. (default: openjdk8)
 128     :mvn-global-settings: The name of the Maven global settings to use for
 129         Maven configuration. (default: global-settings)
 130     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 131     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 132     :mvn-version: Version of maven to use. (default: mvn35)
 133     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
 134         share a Nexus IQ system to avoid project name collision. We recommend
 135         inserting a trailing - dash if using this parameter.
 136         For example 'odl-'. (default: '')
 137     :nexus-iq-stage: Stage the policy evaluation will be run against on
 138         the Nexus IQ Server. (default: 'build')
 139     :stream: Keyword that can be used to represent a release code-name.
 140         Often the same as the branch. (default: master)
 141     :submodule-recursive: Whether to checkout submodules recursively.
 142         (default: true)
 143     :submodule-timeout: Timeout (in minutes) for checkout operation.
 144         (default: 10)
 145
 146     :gerrit_merge_triggers: Override Gerrit Triggers.
 147
 148 Maven JavaDoc Publish
 149 ---------------------
 150
 151 Produces and publishes javadocs for a Maven project.
 152
 153 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 154
 155 :Template Names:
 156
 157     - {project-name}-maven-javadoc-publish-{stream}-{java-version}
 158     - gerrit-maven-javadoc-publish
 159     - github-maven-javadoc-publish
 160
 161 :Comment Trigger: remerge
 162
 163 :Required parameters:
 164
 165     :build-node: The node to run build on.
 166     :javadoc-path: The path in Nexus to deploy javadoc to.
 167     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 168         be configured in defaults.yaml)
 169     :mvn-settings: The name of settings file containing credentials for the project.
 170     :mvn-site-id: Maven Server ID from settings.xml to pull credentials from.
 171         (Note: This setting should be configured in defaults.yaml.)
 172
 173 :Optional parameters:
 174
 175     :branch: The branch to build against. (default: master)
 176     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 177     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 178     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 179     :java-version: Version of Java to use for the build. (default: openjdk8)
 180     :mvn-global-settings: The name of the Maven global settings to use for
 181         Maven configuration. (default: global-settings)
 182     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 183     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 184     :mvn-version: Version of maven to use. (default: mvn35)
 185     :stream: Keyword that can be used to represent a release code-name.
 186         Often the same as the branch. (default: master)
 187     :submodule-recursive: Whether to checkout submodules recursively.
 188         (default: true)
 189     :submodule-timeout: Timeout (in minutes) for checkout operation.
 190         (default: 10)
 191
 192     :gerrit_merge_triggers: Override Gerrit Triggers.
 193
 194 Maven JavaDoc Verify
 195 --------------------
 196
 197 Produces javadocs for a Maven project.
 198
 199 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 200
 201 :Template Names:
 202
 203     - {project-name}-maven-javadoc-verify-{stream}-{java-version}
 204     - gerrit-maven-javadoc-verify
 205     - github-maven-javadoc-verify
 206
 207 :Comment Trigger: recheck|reverify
 208
 209 :Required parameters:
 210     :build-node:    The node to run build on.
 211     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 212         be configured in defaults.yaml)
 213     :mvn-settings: The name of settings file containing credentials for the project.
 214
 215 :Optional parameters:
 216
 217     :branch: The branch to build against. (default: master)
 218     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 219     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 220     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
 221     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 222     :java-version: Version of Java to use for the build. (default: openjdk8)
 223     :mvn-global-settings: The name of the Maven global settings to use for
 224         Maven configuration. (default: global-settings)
 225     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 226     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 227     :mvn-version: Version of maven to use. (default: mvn35)
 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     :submodule-timeout: Timeout (in minutes) for checkout operation.
 233         (default: 10)
 234
 235     :gerrit_verify_triggers: Override Gerrit Triggers.
 236
 237 Maven Merge
 238 -----------
 239
 240 Merge job which runs `mvn clean deploy` to build a project.
 241
 242 This job pushes files to Nexus using cURL instead of allowing the Maven deploy
 243 goal to push the upload. This is to get around the issue that Maven deploy does
 244 not properly support uploading files at the end of the build and instead pushes
 245 as it goes. There exists a `-Ddeploy-at-end` feature however it does not work
 246 with extensions.
 247
 248 This job uses the following strategy to deploy jobs to Nexus:
 249
 250 1. `wget -r` to fetch maven-metadata.xml from Nexus
 251 2. `mvn deploy -DaltDeploymentRepository` to prepare files for upload
 252 3. Removes untouched maven-metadata.xml files before upload
 253 4. Use lftools (cURL) upload script to push artifacts to Nexus
 254
 255 :Template Names:
 256
 257     - {project-name}-maven-merge-{stream}
 258     - gerrit-maven-merge
 259     - github-maven-merge
 260
 261 :Comment Trigger: remerge
 262
 263 :Required parameters:
 264
 265     :build-node: The node to run build on.
 266     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 267         be configured in defaults.yaml)
 268     :mvn-settings: The name of settings file containing credentials for the project.
 269     :mvn-snapshot-id: Maven Server ID from settings.xml to pull credentials from.
 270         (Note: This setting should be configured in defaults.yaml.)
 271     :nexus-snapshot-repo: The repository id of the Nexus snapshot repo to deploy to.
 272
 273 :Optional parameters:
 274
 275     :branch: Git branch to fetch for the build. (default: master)
 276     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 277     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 278     :cron: Cron schedule when to trigger the job. This parameter also
 279         supports multiline input via YAML pipe | character in cases where
 280         one may want to provide more than 1 cron timer. (default: 'H H * * 0'
 281         to run weekly)
 282     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 283     :java-version: Version of Java to use for the build. (default: openjdk8)
 284     :mvn-global-settings: The name of the Maven global settings to use for
 285         Maven configuration. (default: global-settings)
 286     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 287     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 288     :mvn-version: Version of maven to use. (default: mvn35)
 289     :nexus-cut-dirs: Number of directories to cut from file path for `wget -r`.
 290     :stream: Keyword that can be used to represent a release code-name.
 291         Often the same as the branch. (default: master)
 292     :submodule-recursive: Whether to checkout submodules recursively.
 293         (default: true)
 294     :submodule-timeout: Timeout (in minutes) for checkout operation.
 295         (default: 10)
 296     :gerrit_merge_triggers: Override Gerrit Triggers.
 297     :gerrit_trigger_file_paths: Override file paths which can be used to
 298         filter which file modifications will trigger a build.
 299
 300 Maven Merge for Docker
 301 ----------------------
 302
 303 Produces a snapshot docker image in a Nexus registry. Appropriate for
 304 Java projects that do not need to deploy any POM or JAR files.
 305
 306 Similar to Maven Merge as described above but logs in to Docker
 307 registries first and skips the lf-maven-deploy builder. The project
 308 POM file should invoke a plugin to build and push a Docker image. The
 309 base image should be pulled from the registry in the environment
 310 variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
 311 registry in the environment variable CONTAINER_PUSH_REGISTRY.
 312
 313 :Template Names:
 314
 315     - {project-name}-maven-docker-merge-{stream}
 316     - gerrit-maven-docker-merge
 317     - github-maven-docker-merge
 318
 319 :Required parameters:
 320
 321     :container-public-registry: Docker registry source with base images.
 322     :container-snapshot-registry: Docker registry target for the deploy action.
 323
 324 All other required and optional parameters are identical to the Maven Merge job
 325 described above.
 326
 327 Maven Stage
 328 -----------
 329
 330 Produces a release candidate by creating a staging repo in Nexus.
 331
 332 The staging repo name is in the format PROJECT-NUMBER for example "aaa-1234",
 333 "autorelease-2000", "odlparent-1201", etc...
 334
 335 This job runs a Maven build and deploys to $WORKSPACE/m2repo directory. This
 336 directory is then used later to deploy to Nexus.
 337
 338 :Template Names:
 339
 340     - {project-name}-maven-stage-{stream}
 341     - gerrit-maven-stage
 342     - github-maven-stage
 343
 344 :Required parameters:
 345
 346     :build-node: The node to run build on.
 347     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 348         be configured in defaults.yaml)
 349     :mvn-settings: The name of settings file containing credentials for the project.
 350     :mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
 351         (Note: This setting should be configured in defaults.yaml.)
 352     :staging-profile-id: Profile ID of the project's Nexus staging profile.
 353
 354 :Optional parameters:
 355
 356     :archive-artifacts: Artifacts to archive to the logs server (default: '').
 357     :branch: The branch to build against. (default: master)
 358     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 359     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 360     :cron: Cron schedule when to trigger the job. This parameter also
 361         supports multiline input via YAML pipe | character in cases where
 362         one may want to provide more than 1 cron timer. (default: '')
 363     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
 364     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 365     :java-version: Version of Java to use for the build. (default: openjdk8)
 366     :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
 367         that want to release to Maven Central. If set the parameter
 368         ``ossrh-profile-id`` also needs to be set. (default: false)
 369     :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
 370     :mvn-global-settings: The name of the Maven global settings to use for
 371         Maven configuration. (default: global-settings)
 372     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 373     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 374     :mvn-version: Version of maven to use. (default: mvn35)
 375     :maven-versions-plugin-set-version: New version to use in Maven versions plugin. (default: '')
 376     :ossrh-profile-id: Profile ID for project as provided by OSSRH.
 377         (default: '')
 378     :sign-artifacts: Sign artifacts with Sigul. (default: false)
 379     :stream: Keyword that can be used to represent a release code-name.
 380         Often the same as the branch. (default: master)
 381     :submodule-recursive: Whether to checkout submodules recursively.
 382         (default: true)
 383     :submodule-timeout: Timeout (in minutes) for checkout operation.
 384         (default: 10)
 385
 386     :gerrit_release_triggers: Override Gerrit Triggers.
 387
 388 Maven Stage for Docker
 389 ----------------------
 390
 391 Produces a release candidate docker image in a Nexus registry.
 392 Appropriate for Java projects that do not need to deploy any POM or
 393 JAR files.
 394
 395 Similar to Maven Stage as described above but logs in to Docker
 396 registries first and skips the lf-maven-deploy builder. The project
 397 POM file should invoke a plugin to build and push a Docker image. The
 398 base image should be pulled from the registry in the environment
 399 variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
 400 registry in the environment variable CONTAINER_PUSH_REGISTRY.
 401
 402 :Template Names:
 403
 404     - {project-name}-maven-docker-stage-{stream}
 405     - gerrit-maven-docker-stage
 406     - github-maven-docker-stage
 407
 408 :Required parameters:
 409
 410     :container-public-registry: Docker registry source with base images.
 411     :container-staging-registry: Docker registry target for the deploy action.
 412
 413 All other required and optional parameters are identical to the Maven Stage job
 414 described above.
 415
 416 .. _maven-sonar:
 417
 418 Maven Sonar
 419 -----------
 420
 421 Sonar job which runs mvn clean install then publishes to Sonar.
 422
 423 This job purposely only runs on the master branch as there are Additional
 424 configuration needed to support multiple branches and there's not much
 425 interest in that kind of support.
 426
 427 :Template Names:
 428
 429     - {project-name}-sonar
 430     - gerrit-maven-sonar
 431     - github-maven-sonar
 432
 433 :Comment Trigger: run-sonar
 434
 435 :Required parameters:
 436
 437     :build-node: The node to run build on.
 438     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 439         be configured in defaults.yaml)
 440     :mvn-settings: The name of settings file containing credentials for the project.
 441
 442 :Optional parameters:
 443
 444     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 445     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 446     :cron: Cron schedule when to trigger the job. This parameter also
 447         supports multiline input via YAML pipe | character in cases where
 448         one may want to provide more than 1 cron timer.  (default: 'H H * * 6'
 449         to run weekly)
 450     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 451     :java-version: Version of Java to use for the build. (default: openjdk8)
 452     :mvn-global-settings: The name of the Maven global settings to use for
 453         Maven configuration. (default: global-settings)
 454     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 455     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 456     :mvn-version: Version of maven to use. (default: mvn35)
 457     :sonar-mvn-goals: Maven goals to run for sonar analysis.
 458         (default: sonar:sonar)
 459     :sonarcloud: Whether or not to use SonarCloud ``true|false``.
 460         (default: false)
 461     :sonarcloud-project-key: SonarCloud project key. (default: '')
 462     :sonarcloud-project-organization: SonarCloud project organization.
 463         (default: '')
 464     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 465     :stream: Keyword that can be used to represent a release code-name.
 466         Often the same as the branch. (default: master)
 467     :submodule-recursive: Whether to checkout submodules recursively.
 468         (default: true)
 469     :submodule-timeout: Timeout (in minutes) for checkout operation.
 470         (default: 10)
 471
 472     :gerrit_sonar_triggers: Override Gerrit Triggers.
 473
 474
 475 SonarCloud Example:
 476
 477 .. literalinclude:: ../../.jjb-test/lf-maven-jobs/maven-sonarcloud.yaml
 478    :language: yaml
 479
 480 Maven Verify
 481 ------------
 482
 483 Verify job which runs mvn clean install to test a project build..
 484
 485 :Template Names:
 486
 487     - {project-name}-maven-verify-{stream}-{mvn-version}-{java-version}
 488     - gerrit-maven-verify
 489     - github-maven-verify
 490
 491 :Comment Trigger: recheck|reverify
 492
 493 :Required parameters:
 494
 495     :build-node: The node to run build on.
 496     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 497         be configured in defaults.yaml)
 498     :mvn-settings: The name of settings file containing credentials for the project.
 499
 500 :Optional parameters:
 501
 502     :branch: Git branch to fetch for the build. (default: master)
 503     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 504     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 505     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 506     :java-version: Version of Java to use for the build. (default: openjdk8)
 507     :mvn-global-settings: The name of the Maven global settings to use for
 508         Maven configuration. (default: global-settings)
 509     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 510     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 511     :mvn-version: Version of maven to use. (default: mvn35)
 512     :stream: Keyword that can be used to represent a release code-name.
 513         Often the same as the branch. (default: master)
 514     :submodule-recursive: Whether to checkout submodules recursively.
 515         (default: true)
 516     :submodule-timeout: Timeout (in minutes) for checkout operation.
 517         (default: 10)
 518
 519     :gerrit_verify_triggers: Override Gerrit Triggers.
 520     :gerrit_trigger_file_paths: Override file paths which can be used to
 521         filter which file modifications will trigger a build.
 522
 523 Maven Verify for Docker
 524 -----------------------
 525
 526 Similar to Maven Verify as described above but logs in to Docker
 527 registries first. The project POM file should invoke a plugin to build
 528 a Docker image. The base image should be pulled from the registry in
 529 the environment variable CONTAINER_PULL_REGISTRY.
 530
 531 :Template Names:
 532
 533     - {project-name}-maven-docker-verify-{stream}-{mvn-version}-{java-version}
 534     - gerrit-maven-docker-verify
 535     - github-maven-docker-verify
 536
 537 :Required parameters:
 538
 539     :container-public-registry: Docker registry source with base images.
 540
 541 All other required and optional parameters are identical to the Maven Verify job
 542 described above.
 543
 544 Maven Verify w/ Dependencies
 545 ----------------------------
 546
 547 Verify job which runs mvn clean install to test a project build /w deps
 548
 549 This job can be used to verify a patch in conjunction to all of the
 550 upstream patches it depends on. The user of this job can provide a list
 551 via comment trigger.
 552
 553 :Template Names:
 554
 555     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
 556     - gerrit-maven-verify-dependencies
 557
 558 :Comment Trigger: recheck: SPACE_SEPARATED_LIST_OF_PATCHES
 559
 560 :Required parameters:
 561
 562     :build-node: The node to run build on.
 563     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 564         be configured in defaults.yaml)
 565     :mvn-settings: The name of settings file containing credentials for the project.
 566
 567 :Optional parameters:
 568
 569     :branch: Git branch to fetch for the build. (default: master)
 570     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 571     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 572     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 573     :java-version: Version of Java to use for the build. (default: openjdk8)
 574     :mvn-global-settings: The name of the Maven global settings to use for
 575         Maven configuration. (default: global-settings)
 576     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 577     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 578     :mvn-version: Version of maven to use. (default: mvn35)
 579     :stream: Keyword that can be used to represent a release code-name.
 580         Often the same as the branch. (default: master)
 581     :submodule-recursive: Whether to checkout submodules recursively.
 582         (default: true)
 583     :submodule-timeout: Timeout (in minutes) for checkout operation.
 584         (default: 10)
 585
 586     :gerrit_verify_triggers: Override Gerrit Triggers.
 587     :gerrit_trigger_file_paths: Override file paths which can be used to
 588         filter which file modifications will trigger a build.