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