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