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