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