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
 297     :gerrit_merge_triggers: Override Gerrit Triggers.
 298     :gerrit_trigger_file_paths: Override file paths which can be used to
 299         filter which file modifications will trigger a build.
 300
 301 Maven Stage
 302 -----------
 303
 304 Produces a release candidate by creating a staging repo in Nexus.
 305
 306 The staging repo name is in the format PROJECT-NUMBER for example "aaa-1234",
 307 "autorelease-2000", "odlparent-1201", etc...
 308
 309 This job runs a Maven build and deploys to $WORKSPACE/m2repo directory. This
 310 directory is then used later to deploy to Nexus.
 311
 312 :Template Names:
 313
 314     - {project-name}-maven-stage-{stream}
 315     - gerrit-maven-stage
 316     - github-maven-stage
 317
 318 :Required parameters:
 319
 320     :build-node: The node to run build on.
 321     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 322         be configured in defaults.yaml)
 323     :mvn-settings: The name of settings file containing credentials for the project.
 324     :mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
 325         (Note: This setting should be configured in defaults.yaml.)
 326     :staging-profile-id: Profile ID of the project's Nexus staging profile.
 327
 328 :Optional parameters:
 329
 330     :archive-artifacts: Artifacts to archive to the logs server (default: '').
 331     :branch: The branch to build against. (default: master)
 332     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 333     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 334     :cron: Cron schedule when to trigger the job. This parameter also
 335         supports multiline input via YAML pipe | character in cases where
 336         one may want to provide more than 1 cron timer. (default: '')
 337     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
 338     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 339     :java-version: Version of Java to use for the build. (default: openjdk8)
 340     :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
 341         that want to release to Maven Central. If set the parameter
 342         ``ossrh-profile-id`` also needs to be set. (default: false)
 343     :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
 344     :mvn-global-settings: The name of the Maven global settings to use for
 345         Maven configuration. (default: global-settings)
 346     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 347     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 348     :mvn-version: Version of maven to use. (default: mvn35)
 349     :maven-versions-plugin-set-version: New version to use in Maven versions plugin. (default: '')
 350     :ossrh-profile-id: Profile ID for project as provided by OSSRH.
 351         (default: '')
 352     :sign-artifacts: Sign artifacts with Sigul. (default: false)
 353     :stream: Keyword that can be used to represent a release code-name.
 354         Often the same as the branch. (default: master)
 355     :submodule-recursive: Whether to checkout submodules recursively.
 356         (default: true)
 357     :submodule-timeout: Timeout (in minutes) for checkout operation.
 358         (default: 10)
 359
 360     :gerrit_release_triggers: Override Gerrit Triggers.
 361
 362 .. _maven-sonar:
 363
 364 Maven Sonar
 365 -----------
 366
 367 Sonar job which runs mvn clean install then publishes to Sonar.
 368
 369 This job purposely only runs on the master branch as there are Additional
 370 configuration needed to support multiple branches and there's not much
 371 interest in that kind of support.
 372
 373 :Template Names:
 374
 375     - {project-name}-sonar
 376     - gerrit-maven-sonar
 377     - github-maven-sonar
 378
 379 :Comment Trigger: run-sonar
 380
 381 :Required parameters:
 382
 383     :build-node: The node to run build on.
 384     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 385         be configured in defaults.yaml)
 386     :mvn-settings: The name of settings file containing credentials for the project.
 387
 388 :Optional parameters:
 389
 390     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 391     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 392     :cron: Cron schedule when to trigger the job. This parameter also
 393         supports multiline input via YAML pipe | character in cases where
 394         one may want to provide more than 1 cron timer.  (default: 'H H * * 6'
 395         to run weekly)
 396     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 397     :java-version: Version of Java to use for the build. (default: openjdk8)
 398     :mvn-global-settings: The name of the Maven global settings to use for
 399         Maven configuration. (default: global-settings)
 400     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 401     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 402     :mvn-version: Version of maven to use. (default: mvn35)
 403     :sonar-mvn-goals: Maven goals to run for sonar analysis.
 404         (default: sonar:sonar)
 405     :sonarcloud: Whether or not to use SonarCloud ``true|false``.
 406         (default: false)
 407     :sonarcloud-project-key: SonarCloud project key. (default: '')
 408     :sonarcloud-project-organization: SonarCloud project organization.
 409         (default: '')
 410     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 411     :stream: Keyword that can be used to represent a release code-name.
 412         Often the same as the branch. (default: master)
 413     :submodule-recursive: Whether to checkout submodules recursively.
 414         (default: true)
 415     :submodule-timeout: Timeout (in minutes) for checkout operation.
 416         (default: 10)
 417
 418     :gerrit_sonar_triggers: Override Gerrit Triggers.
 419
 420
 421 SonarCloud Example:
 422
 423 .. literalinclude:: ../../.jjb-test/lf-maven-jobs/maven-sonarcloud.yaml
 424    :language: yaml
 425
 426 Maven Verify
 427 ------------
 428
 429 Verify job which runs mvn clean install to test a project build..
 430
 431 :Template Names:
 432
 433     - {project-name}-maven-verify-{stream}-{mvn-version}-{java-version}
 434     - gerrit-maven-verify
 435     - github-maven-verify
 436
 437 :Comment Trigger: recheck|reverify
 438
 439 :Required parameters:
 440
 441     :build-node: The node to run build on.
 442     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 443         be configured in defaults.yaml)
 444     :mvn-settings: The name of settings file containing credentials for the project.
 445
 446 :Optional parameters:
 447
 448     :branch: Git branch to fetch for the build. (default: master)
 449     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 450     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 451     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 452     :java-version: Version of Java to use for the build. (default: openjdk8)
 453     :mvn-global-settings: The name of the Maven global settings to use for
 454         Maven configuration. (default: global-settings)
 455     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 456     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 457     :mvn-version: Version of maven to use. (default: mvn35)
 458     :stream: Keyword that can be used to represent a release code-name.
 459         Often the same as the branch. (default: master)
 460     :submodule-recursive: Whether to checkout submodules recursively.
 461         (default: true)
 462     :submodule-timeout: Timeout (in minutes) for checkout operation.
 463         (default: 10)
 464
 465     :gerrit_verify_triggers: Override Gerrit Triggers.
 466     :gerrit_trigger_file_paths: Override file paths which can be used to
 467         filter which file modifications will trigger a build.
 468
 469 Maven Verify /w Dependencies
 470 ----------------------------
 471
 472 Verify job which runs mvn clean install to test a project build /w deps
 473
 474 This job can be used to verify a patch in conjunction to all of the
 475 upstream patches it depends on. The user of this job can provide a list
 476 via comment trigger.
 477
 478 :Template Names:
 479
 480     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
 481     - gerrit-maven-verify-dependencies
 482
 483 :Comment Trigger: recheck: SPACE_SEPERATED_LIST_OF_PATCHES
 484
 485 :Required parameters:
 486
 487     :build-node: The node to run build on.
 488     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 489         be configured in defaults.yaml)
 490     :mvn-settings: The name of settings file containing credentials for the project.
 491
 492 :Optional parameters:
 493
 494     :branch: Git branch to fetch for the build. (default: master)
 495     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 496     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 497     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 498     :java-version: Version of Java to use for the build. (default: openjdk8)
 499     :mvn-global-settings: The name of the Maven global settings to use for
 500         Maven configuration. (default: global-settings)
 501     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 502     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 503     :mvn-version: Version of maven to use. (default: mvn35)
 504     :stream: Keyword that can be used to represent a release code-name.
 505         Often the same as the branch. (default: master)
 506     :submodule-recursive: Whether to checkout submodules recursively.
 507         (default: true)
 508     :submodule-timeout: Timeout (in minutes) for checkout operation.
 509         (default: 10)
 510
 511     :gerrit_verify_triggers: Override Gerrit Triggers.
 512     :gerrit_trigger_file_paths: Override file paths which can be used to
 513         filter which file modifications will trigger a build.