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