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-stage
  65 ---------------
  66
  67 Calls the maven stage script to push artifacts to a Nexus staging repository.
  68
  69 lf-update-java-alternatives
  70 ---------------------------
  71
  72 Setup Java alternatives for the Distro.
  73
  74 :Required Parameters:
  75
  76     :java-version: Version of Java to set as the default Java.
  77         Eg. openjdk8
  78
  79 Job Templates
  80 =============
  81
  82 Maven CLM
  83 ---------
  84
  85 Produces a CLM scan of the code into Nexus IQ Server.
  86
  87 :Template Names:
  88
  89     - {project-name}-maven-clm-{stream}
  90     - gerrit-maven-clm
  91     - github-maven-clm
  92
  93 :Comment Trigger: run-clm
  94
  95 :Required parameters:
  96
  97     :build-node:    The node to run build on.
  98     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  99         be configured in defaults.yaml)
 100     :mvn-settings: The name of settings file containing credentials for the project.
 101
 102 :Optional parameters:
 103
 104     :branch: The branch to build against. (default: master)
 105     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 106     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 107     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 108     :java-version: Version of Java to use for the build. (default: openjdk8)
 109     :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
 110         that want to release to Maven Central. If set the parameter
 111         ``ossrh-profile-id`` also needs to be set. (default: false)
 112     :mvn-global-settings: The name of the Maven global settings to use for
 113         Maven configuration. (default: global-settings)
 114     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 115     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 116     :mvn-version: Version of maven to use. (default: mvn35)
 117     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
 118         share a Nexus IQ system to avoid project name collision. We recommend
 119         inserting a trailing - dash if using this parameter.
 120         For example 'odl-'. (default: '')
 121     :nexus-iq-stage: Stage the policy evaluation will be run against on
 122         the Nexus IQ Server. (default: 'build')
 123     :ossrh-profile-id: Profile ID for project as provided by OSSRH.
 124         (default: '')
 125     :stream: Keyword that can be used to represent a release code-name.
 126         Often the same as the branch. (default: master)
 127     :submodule-recursive: Whether to checkout submodules recursively.
 128         (default: true)
 129     :submodule-timeout: Timeout (in minutes) for checkout operation.
 130         (default: 10)
 131
 132     :gerrit_merge_triggers: Override Gerrit Triggers.
 133
 134 Maven JavaDoc Publish
 135 ---------------------
 136
 137 Produces and publishes javadocs for a Maven project.
 138
 139 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 140
 141 :Template Names:
 142
 143     - {project-name}-maven-javadoc-publish-{stream}-{java-version}
 144     - gerrit-maven-javadoc-publish
 145     - github-maven-javadoc-publish
 146
 147 :Comment Trigger: remerge
 148
 149 :Required parameters:
 150
 151     :build-node: The node to run build on.
 152     :javadoc-path: The path in Nexus to deploy javadoc to.
 153     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 154         be configured in defaults.yaml)
 155     :mvn-settings: The name of settings file containing credentials for the project.
 156     :mvn-site-id: Maven Server ID from settings.xml to pull credentials from.
 157         (Note: This setting should be configured in defaults.yaml.)
 158
 159 :Optional parameters:
 160
 161     :branch: The branch to build against. (default: master)
 162     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 163     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 164     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 165     :java-version: Version of Java to use for the build. (default: openjdk8)
 166     :mvn-global-settings: The name of the Maven global settings to use for
 167         Maven configuration. (default: global-settings)
 168     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 169     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 170     :mvn-version: Version of maven to use. (default: mvn35)
 171     :stream: Keyword that can be used to represent a release code-name.
 172         Often the same as the branch. (default: master)
 173     :submodule-recursive: Whether to checkout submodules recursively.
 174         (default: true)
 175     :submodule-timeout: Timeout (in minutes) for checkout operation.
 176         (default: 10)
 177
 178     :gerrit_merge_triggers: Override Gerrit Triggers.
 179
 180 Maven JavaDoc Verify
 181 --------------------
 182
 183 Produces javadocs for a Maven project.
 184
 185 Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 186
 187 :Template Names:
 188
 189     - {project-name}-maven-javadoc-verify-{stream}-{java-version}
 190     - gerrit-maven-javadoc-verify
 191     - github-maven-javadoc-verify
 192
 193 :Comment Trigger: recheck|reverify
 194
 195 :Required parameters:
 196     :build-node:    The node to run build on.
 197     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 198         be configured in defaults.yaml)
 199     :mvn-settings: The name of settings file containing credentials for the project.
 200
 201 :Optional parameters:
 202
 203     :branch: The branch to build against. (default: master)
 204     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 205     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 206     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
 207     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 208     :java-version: Version of Java to use for the build. (default: openjdk8)
 209     :mvn-global-settings: The name of the Maven global settings to use for
 210         Maven configuration. (default: global-settings)
 211     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 212     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 213     :mvn-version: Version of maven to use. (default: mvn35)
 214     :stream: Keyword that can be used to represent a release code-name.
 215         Often the same as the branch. (default: master)
 216     :submodule-recursive: Whether to checkout submodules recursively.
 217         (default: true)
 218     :submodule-timeout: Timeout (in minutes) for checkout operation.
 219         (default: 10)
 220
 221     :gerrit_verify_triggers: Override Gerrit Triggers.
 222
 223 Maven Merge
 224 -----------
 225
 226 Merge job which runs `mvn clean deploy` to build a project.
 227
 228 This job pushes files to Nexus using cURL instead of allowing the Maven deploy
 229 goal to push the upload. This is to get around the issue that Maven deploy does
 230 not properly support uploading files at the end of the build and instead pushes
 231 as it goes. There exists a `-Ddeploy-at-end` feature however it does not work
 232 with extensions.
 233
 234 This job uses the following strategy to deploy jobs to Nexus:
 235
 236 1. `wget -r` to fetch maven-metadata.xml from Nexus
 237 2. `mvn deploy -DaltDeploymentRepository` to prepare files for upload
 238 3. Removes untouched maven-metadata.xml files before upload
 239 4. Use lftools (cURL) upload script to push artifacts to Nexus
 240
 241 :Template Names:
 242
 243     - {project-name}-maven-merge-{stream}
 244     - gerrit-maven-merge
 245     - github-maven-merge
 246
 247 :Comment Trigger: remerge
 248
 249 :Required parameters:
 250
 251     :build-node: The node to run build on.
 252     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 253         be configured in defaults.yaml)
 254     :mvn-settings: The name of settings file containing credentials for the project.
 255     :mvn-snapshot-id: Maven Server ID from settings.xml to pull credentials from.
 256         (Note: This setting should be configured in defaults.yaml.)
 257     :nexus-snapshot-repo: The repository id of the Nexus snapshot repo to deploy to.
 258
 259 :Optional parameters:
 260
 261     :branch: Git branch to fetch for the build. (default: master)
 262     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 263     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 264     :cron: Cron schedule when to trigger the job. This parameter also
 265         supports multiline input via YAML pipe | character in cases where
 266         one may want to provide more than 1 cron timer. (default: 'H H * * 0'
 267         to run weekly)
 268     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 269     :java-version: Version of Java to use for the build. (default: openjdk8)
 270     :mvn-global-settings: The name of the Maven global settings to use for
 271         Maven configuration. (default: global-settings)
 272     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 273     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 274     :mvn-version: Version of maven to use. (default: mvn35)
 275     :nexus-cut-dirs: Number of directories to cut from file path for `wget -r`.
 276     :stream: Keyword that can be used to represent a release code-name.
 277         Often the same as the branch. (default: master)
 278     :submodule-recursive: Whether to checkout submodules recursively.
 279         (default: true)
 280     :submodule-timeout: Timeout (in minutes) for checkout operation.
 281         (default: 10)
 282
 283     :gerrit_merge_triggers: Override Gerrit Triggers.
 284     :gerrit_trigger_file_paths: Override file paths which can be used to
 285         filter which file modifications will trigger a build.
 286
 287 Maven Stage
 288 -----------
 289
 290 Produces a release candidate by creating a staging repo in Nexus.
 291
 292 The staging repo name is in the format PROJECT-NUMBER for example "aaa-1234",
 293 "autorelease-2000", "odlparent-1201", etc...
 294
 295 This job runs a Maven build and deploys to $WORKSPACE/m2repo directory. This
 296 directory is then used later to deploy to Nexus.
 297
 298 :Template Names:
 299
 300     - {project-name}-maven-stage-{stream}
 301     - gerrit-maven-stage
 302     - github-maven-stage
 303
 304 :Required parameters:
 305
 306     :build-node: The node to run build on.
 307     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 308         be configured in defaults.yaml)
 309     :mvn-settings: The name of settings file containing credentials for the project.
 310     :mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
 311         (Note: This setting should be configured in defaults.yaml.)
 312     :staging-profile-id: Profile ID of the project's Nexus staging profile.
 313
 314 :Optional parameters:
 315
 316     :archive-artifacts: Artifacts to archive to the logs server (default: '').
 317     :branch: The branch to build against. (default: master)
 318     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 319     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 320     :cron: Cron schedule when to trigger the job. This parameter also
 321         supports multiline input via YAML pipe | character in cases where
 322         one may want to provide more than 1 cron timer. (default: '')
 323     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
 324     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 325     :java-version: Version of Java to use for the build. (default: openjdk8)
 326     :mvn-global-settings: The name of the Maven global settings to use for
 327         Maven configuration. (default: global-settings)
 328     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 329     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 330     :mvn-version: Version of maven to use. (default: mvn35)
 331     :sign-artifacts: Sign artifacts with Sigul. (default: false)
 332     :stream: Keyword that can be used to represent a release code-name.
 333         Often the same as the branch. (default: master)
 334     :submodule-recursive: Whether to checkout submodules recursively.
 335         (default: true)
 336     :submodule-timeout: Timeout (in minutes) for checkout operation.
 337         (default: 10)
 338
 339     :gerrit_release_triggers: Override Gerrit Triggers.
 340
 341 .. _maven-sonar:
 342
 343 Maven Sonar
 344 -----------
 345
 346 Sonar job which runs mvn clean install then publishes to Sonar.
 347
 348 This job purposely only runs on the master branch as there are Additional
 349 configuration needed to support multiple branches and there's not much
 350 interest in that kind of support.
 351
 352 :Template Names:
 353
 354     - {project-name}-sonar
 355     - gerrit-maven-sonar
 356     - github-maven-sonar
 357
 358 :Comment Trigger: run-sonar
 359
 360 :Required parameters:
 361
 362     :build-node: The node to run build on.
 363     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 364         be configured in defaults.yaml)
 365     :mvn-settings: The name of settings file containing credentials for the project.
 366
 367 :Optional parameters:
 368
 369     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 370     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 371     :cron: Cron schedule when to trigger the job. This parameter also
 372         supports multiline input via YAML pipe | character in cases where
 373         one may want to provide more than 1 cron timer.  (default: 'H H * * 6'
 374         to run weekly)
 375     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 376     :java-version: Version of Java to use for the build. (default: openjdk8)
 377     :mvn-global-settings: The name of the Maven global settings to use for
 378         Maven configuration. (default: global-settings)
 379     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 380     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 381     :mvn-version: Version of maven to use. (default: mvn35)
 382     :sonar-mvn-goals: Maven goals to run for sonar analysis.
 383         (default: sonar:sonar)
 384     :sonarcloud: Whether or not to use SonarCloud ``true|false``.
 385         (default: false)
 386     :sonarcloud-project-key: SonarCloud project key. (default: '')
 387     :sonarcloud-project-organization: SonarCloud project organization.
 388         (default: '')
 389     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 390     :stream: Keyword that can be used to represent a release code-name.
 391         Often the same as the branch. (default: master)
 392     :submodule-recursive: Whether to checkout submodules recursively.
 393         (default: true)
 394     :submodule-timeout: Timeout (in minutes) for checkout operation.
 395         (default: 10)
 396
 397     :gerrit_sonar_triggers: Override Gerrit Triggers.
 398
 399
 400 SonarCloud Example:
 401
 402 .. literalinclude:: ../../.jjb-test/lf-maven-jobs/maven-sonarcloud.yaml
 403    :language: yaml
 404
 405 Maven Verify
 406 ------------
 407
 408 Verify job which runs mvn clean install to test a project build..
 409
 410 :Template Names:
 411
 412     - {project-name}-maven-verify-{stream}-{mvn-version}-{java-version}
 413     - gerrit-maven-verify
 414     - github-maven-verify
 415
 416 :Comment Trigger: recheck|reverify
 417
 418 :Required parameters:
 419
 420     :build-node: The node to run build on.
 421     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 422         be configured in defaults.yaml)
 423     :mvn-settings: The name of settings file containing credentials for the project.
 424
 425 :Optional parameters:
 426
 427     :branch: Git branch to fetch for the build. (default: master)
 428     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 429     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 430     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 431     :java-version: Version of Java to use for the build. (default: openjdk8)
 432     :mvn-global-settings: The name of the Maven global settings to use for
 433         Maven configuration. (default: global-settings)
 434     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 435     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 436     :mvn-version: Version of maven to use. (default: mvn35)
 437     :stream: Keyword that can be used to represent a release code-name.
 438         Often the same as the branch. (default: master)
 439     :submodule-recursive: Whether to checkout submodules recursively.
 440         (default: true)
 441     :submodule-timeout: Timeout (in minutes) for checkout operation.
 442         (default: 10)
 443
 444     :gerrit_verify_triggers: Override Gerrit Triggers.
 445     :gerrit_trigger_file_paths: Override file paths which can be used to
 446         filter which file modifications will trigger a build.
 447
 448 Maven Verify /w Dependencies
 449 ----------------------------
 450
 451 Verify job which runs mvn clean install to test a project build /w deps
 452
 453 This job can be used to verify a patch in conjunction to all of the
 454 upstream patches it depends on. The user of this job can provide a list
 455 via comment trigger.
 456
 457 :Template Names:
 458
 459     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
 460     - gerrit-maven-verify-dependencies
 461
 462 :Comment Trigger: recheck: SPACE_SEPERATED_LIST_OF_PATCHES
 463
 464 :Required parameters:
 465
 466     :build-node: The node to run build on.
 467     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 468         be configured in defaults.yaml)
 469     :mvn-settings: The name of settings file containing credentials for the project.
 470
 471 :Optional parameters:
 472
 473     :branch: Git branch to fetch for the build. (default: master)
 474     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 475     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 476     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 477     :java-version: Version of Java to use for the build. (default: openjdk8)
 478     :mvn-global-settings: The name of the Maven global settings to use for
 479         Maven configuration. (default: global-settings)
 480     :mvn-opts: Sets MAVEN_OPTS. (default: '')
 481     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
 482     :mvn-version: Version of maven to use. (default: mvn35)
 483     :stream: Keyword that can be used to represent a release code-name.
 484         Often the same as the branch. (default: master)
 485     :submodule-recursive: Whether to checkout submodules recursively.
 486         (default: true)
 487     :submodule-timeout: Timeout (in minutes) for checkout operation.
 488         (default: 10)
 489
 490     :gerrit_verify_triggers: Override Gerrit Triggers.
 491     :gerrit_trigger_file_paths: Override file paths which can be used to
 492         filter which file modifications will trigger a build.