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