docs/jjb/lf-maven-jobs.rst

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