Jenkins Pipeline Library

Since Jenkins Pipeline has reached a certain state of production scripted pipelines are the way to go.

But: Not everything known from the UI is available in Pipeline and configuring and writing scripts is not so easy for the normal developer.

The target of this library is to take out some complexity (and yes adding some too) of the pipeline creation and to bring back some known functionality (for example GIT_BRANCH and SCM_URL environment variables, mail notification on still unstable etc.)

Want to see an example? Have look at Usage examples

Table of contents

• Key concepts
• Requirements
• Steps
• Utilities
• Credential and managed file auto lookup
• Support for command line execution
• Setup your environment to use the pipeline library
• Building/Testing
  • Building with maven
• Changes / Version History

Key concepts

The pipeline library was developed with a focus to ease Java and Maven build processes within companies which have a more or less similiar project structure e.g.

• Maven/Java
• local Artifact Server (like Sonatype Nexus or Artifactory)
• GIT

The assumption is that in these environments

• Jenkins has a dedicated user account to checkout code (or one per project)
• the artifact server caches public artifacts and acts as a internal artifact server

:question: So why configure maven repositories and scm credentials in every pipeline?

So the key concepts of the pipeline enable you to

• Auto provide credentials (no worries, only Jenkins credential ids, not the credential itself) (see Credentials)
• Auto provide maven settings (see ManagedFiles)
• configure each job the same way (see ConfigStructure)
• log and see the things you are interested in (see Logging)

to builds.

Running this pipeline library will result in more structured and easier to maintain pipeline scripts.

Configured properly this library enables you to checkout scm with these lines of code:

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*
checkoutScm( (SCM) : [
        (SCM_URL) : "[email protected]/group/project.git",
    ]
)

Or running maven with local and global maven settings with these lines of code:

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*
execMaven( 
    (SCM) : [
        (SCM_URL) : "[email protected]/group/project.git",
    ],
    (MAVEN): [
        (MAVEN_GOALS) : [ "clean", "install" ]
    ]
)

:question: Looking for an example on how a pipeline script looks like when using Pipeline? Have a look at Usage examples

:bulb: Have a look at the setup tutorial to start using Pipeline Library.

Requirements

Have a look at requirements to get the library running.

Steps

The pipeline library comes with the following steps:

• ansible
  • ansible.checkoutRoles
  • ansible.execPlaybook
  • ansible.getGalaxyRoleInfo
  • ansible.installRoles
• checkoutScm
• conditionalStage
• credentials
  • lookupHttpCredential
  • lookupScmCredential
  • lookupSshCredential
• execMaven
• execMavenRelease
• execNpm
• genericConfig
  • load
• getScmUrl
• gitTools
  • mirrorRepository
  • mirrorRepositoryToRemote
  • mirrorRepositoryToWorkspace
  • getFetchOrigin
  • getPushOrigin
  • getParentBranch
• im (instant messaging)
  • im.mattermost()
  • im.teams()
• jenkinsRestApi
  • jenkinsRestApi.findJobsByNameRegex
• managedScripts
  • managedScripts.execJenkinsShellScript
  • managedScripts.execPipelineShellScript
• maven
  • purgeSnapshots
• notify
  • notify.mail
  • notify.mattermost
  • notify.mqtt
  • notify.teams
• setBuildName
• setScmUrl
• setupTools
• sshAgentWrapper
• transferScp
• wrappers
  • wrappers.color

Utilities

• Build Parameter Factory
• Integration Testing
• Logging
  • Logger
  • LogLevel
• Configuration map merging
  • MapUtils
  • MapMergeMode

Credential and managed file auto lookup

• Credentials
  • Credential
  • CredentialParser
  • CredentialConstants
• Generic Configuration
• ManagedFiles
  • ManagedFile
  • ManagedFileParser
  • ManagedFileConstants
• PatternMatching
  • PatternMatchable
  • PatternMatcher

Support for command line execution

• CommandBuilder
• MavenCommandBuilder

Setup your environment to use the pipeline library

Please refer to SetupTutorial for detailed instruction on how to setup the library in your environment.

Building/Testing

The library uses two approaches for testing.

The class parts are tested by unit testing using JUnit/Surefire. All unit tests have the naming format *Test.groovy and are located below test/io.

The step parts are tested by using Jenkins Pipeline Unit with jUnit/Failsafe. All integration tests have the naming format *IT.groovy and are located below test/vars.

Building with maven

mvn clean install

Add license file headers

mvn license:update-file-header

Changes / Version History

Please have a look at the Releases