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