Pipeline Global Library

This repository contains a series of steps and variables for use inside of the Jenkins project’s own Jenkins instance(s).

Check this description of available services.

Useful steps:

buildPlugin

Applies the appropriate defaults for building a Maven- or Gradle-based plugin project on Linux and Windows.

You are advised to be using a 2.x parent POM.

Jenkinsfile

buildPlugin()

Optional arguments

• jdkVersions (default: [8]) - JDK version numbers, must match a version number jdk tool installed

• repo (default: null inherit from Multibranch) - custom Git repository to check out

• failFast (default: true) - instruct Maven tests to fail fast

• platforms (default: ['linux', 'windows']) - Labels matching platforms to execute the steps against in parallel

• jenkinsVersions: (default: [null]) - a matrix of Jenkins baseline versions to build/test against in parallel (null means default, only available for Maven projects)

• findbugs: (default: null) - a map of parameters to run findbugs and/or archive findbugs reports. (only available for Maven projects)

  • run: set to true to add the findbugs:findbugs goal to the maven command.

  • archive: set to true to collect the findbugs report.

  • pattern: (default: '**/target/findbugsXml.xml') the file pattern for the report.

  • unstableTotalAll: (default: null) the warnings threshold for when to mark the build as unstable, see the findbugs step for additional details.

  • unstableNewAll: (default: null) the new warnings threshold for when to mark the build as unstable, see the findbugs step for additional details.

• checkstyle: (default: null) - a map of parameters to run checkstyle and/or archive checkstyle reports. (only available for Maven projects)

  • run: set to true to add the checkstyle:checkstyle goal to the maven command.

  • archive: set to true to collect the checkstyle report.

  • pattern: (default: '**/target/checkstyle-result.xml') the file pattern for the report.

  • unstableTotalAll: (default: null) the violations threshold for when to mark the build as unstable, see the checkstyle step for additional details.

  • unstableNewAll: (default: null) the new violations threshold for when to mark the build as unstable, see the checkstyle step for additional details.

Note	findbugs and checkstyle are only run/archived on the first platform/jdkVersion,jenkinsVersion combination. So in the example below it will run for linux/jdk7 but not on jdk8.

Usage:

Jenkinsfile

buildPlugin(platforms: ['linux'], jdkVersions: [7, 8], findbugs: [archive: true, unstableTotalAll: '0'], checkstyle: [run: true, archive: true])

infra.isTrusted()

Determine whether the Pipeline is executing in an internal "trusted" Jenkins environment

Jenkinsfile

if (infra.isTrusted()) {
    /* perform some trusted action like a deployment */
}

runATH

Runs the Acceptance Test Harness in a configurable way.

The configuration is divided into two parts, one related to the step itself and another related to how the ATH is run. To configure the step just use the step’s parameters described below, to configure the ATH runs a metadata file (in YAML format) is used. Further sections describe the metadata file in detail. Note that if the metadata file does not exist this step will do nothing at all.

The list of step’s params and the related default values are:

athUrl

The URL to get the ATH sources. It can point to a local path (by using the file:// protocol) or a github destination. Defaults to https://github.com/jenkinsci/acceptance-test-harness.git. Can be overridden from the metadata file

athRevision

The ATH revision to use, can be a branch or tag name or a commit id. Defaults to branch master. Can be overridden from the metadata file

metadataFile

A String indicating the file path (relative to where this step is executed) to use as metadata file for the build, more details about the metadata file are provided belows. Defaults to essentials.yml at the location where this step is invoked

jenkins

URI to the jenkins.war, Jenkins version or one of "latest", "latest-rc", "lts" and "lts-rc". Defaults to "latest". For local war files use the file:// protocol in the URI. Can be overriden from the metadata file

Step call example

runATH(metadataFile:"metadata.yml", athRevision: "master", athUrl:"https://github.com/jenkinsci/acceptance-test-harness.git", jenkins: "2.110")

To make it usable in PR builders this step allows users to run the ATH using custom (typically previously built in the same Jenkinsfile) versions of any plugin, for that you need to set the metadata file’s useLocalSnapshots property to true and stash the plugins you want to use in the ATH run. By default you need to stash them with the name localPlugins the step will unstash them when appropriate and use the ATH`s LOCAL_JARS property to run the ATH. You can stash any number of plugins, all of them will be used. You can also stash under other name by setting the env variable RUN_ATH_LOCAL_PLUGINS_STASH_NAME

Using development versions of plugins

node("linux") {
        dir("sources") {
          checkout scm
          List<String> mavenEnv = [
                    "JAVA_HOME=${tool 'jdk8'}",
                    'PATH+JAVA=${JAVA_HOME}/bin',
                    "PATH+MAVEN=${tool 'mvn'}/bin"]
          withEnv(mavenEnv) {
            sh "mvn clean install -DskipTests"
          }
          dir("target") {
           stash includes: '*.hpi', name: 'localPlugins'
          }

          runATH(metadataFile:"metadata.yml", athRevision: "master")
        }
    }

Using custom stash name

    node("linux") {
        dir("sources") {
          checkout scm
          List<String> mavenEnv = [
                    "JAVA_HOME=${tool 'jdk8'}",
                    'PATH+JAVA=${JAVA_HOME}/bin',
                    "PATH+MAVEN=${tool 'mvn'}/bin"]
          withEnv(mavenEnv) {
            sh "mvn clean install -DskipTests"
          }
          dir("target") {
           stash includes: '*.hpi', name: 'snapshots'
          }

          env.RUN_ATH_LOCAL_PLUGINS_STASH_NAME="snapshots"
          runATH(metadataFile:"metadata.yml", athRevision: "master")
        }
    }

The metadata file is a YAML file with the following structure:

metadata

ath:
  athUrl: https://github.com/jenkinsci/acceptance-test-harness.git
  athRevision: acceptance-test-harness-1.59
  jenkins: 2.89.4
  failFast: false
  rerunFailingTestsCount: 0
  useLocalSnapshots: true
  browsers:
    - firefox
    - chrome
  tests:
    - Test1
    - Test2
    - Test3
  categories:
    - Category1
    - Category2

Where:

athUrl

(Optional) The URL to get the ATH sources. It can point to a local path or a github destination. If specified it will override the parameter in the runATH step

athRevision

(Optional) The ATH revision to use can be a branch or tag name or a commit id. If specified it will override the parameter in the runATH step

jenkins

(Optional) URI to the jenkins.war file, Jenkins version or one of "latest", "latest-rc", "lts" and "lts-rc". If specified it will override the parameter in the runATH step

failFast

If the run has to fail fast or not. Defaults to false if not specified

rerunFailingTestsCount

The number of runs per failing test (a la maven). Defaults to zero

useLocalSnapshots

If the ATH should use local versions of the plugins. Defaults to true. Note that if true the runATH expects the local plugins to be stashed, setting this to true without the stash will make the step fail

browsers

The list of browsers to use when running ATH Defaults to firefox. Note that currently only firefox browser is supported, any other will be ignored

tests

The list of tests to run for the component that calls the step. If no particular set of tests or categories is defined the SmokeTest Category of the ATH will be run

categories

The list of Categories to run. Defaults to nothing

In case you want to use the defaults for all properties you can use

metadata

ath: "default"

Please note that a blank metadata file will result in an error