Introduction

Jenkins shared libraries allow code reuse between pipeline projects.

Custom steps can be created for use in pipelines. Shell scripts and other supporting files can be included and used by custom steps or directly by pipelines.

When authoring pipelines and shared libraries, be aware of certain limitations and recommended practices.

• Scripted versus Declarative Pipeline syntax
• Use the Snippet Generator and the Declarative Directive Generator
• Pipeline: Best Practices

Usage

Use the library step to dynamically include a shared library in your pipeline as this keeps the most information in the Jenkinsfile under source control rather than in Jenkins configuration.

A basic Jenkinsfile example:

library identifier: 'jenkins-shared-library@v1.0.0', 
    retriever: modernSCM([
        $class: 'GitSCMSource',
        remote: 'https://github.com/mhicks-cloudbees/jenkins-shared-library.git'
        // remote: 'git@github.com:mhicks-cloudbees/jenkins-shared-library.git',
        // credentialsId: 'git-key'
    ])

pipeline {
    agent any
    stages {
        stage('Hello') {
            steps {
                exampleHelloWorld()
            }
        }
    }
}

Note: This method of referencing a shared library requires using a specific library version (as with @v1.0.0 in the library step above). We recommend against using @master. This prevents your pipeline from using changes in newer versions of the shared library that could cause errors or unexpected behavior. New versions of shared libraries can then be tested separately from standard builds. See releases.

Steps

This shared library defines the following custom steps:

• exampleArgs
• exampleHelloWorld
• exampleResourceScript

exampleArgs

Use named parameters with defaults and a block section. See vars/exampleArgs.groovy.

steps {
    exampleArgs(requiredArg: 'foo', optionalArg: 'bar') {
        echo 'block steps'
    }
}

Example build log output:

[Pipeline] echo
Arguments: [requiredArg:foo, optionalArg:bar, hasDefaultArg:baz]
[Pipeline] echo
Block:org.jenkinsci.plugins.workflow.cps.CpsClosure

Arguments

Argument name	Type	Purpose	Default	Required?
requiredArg	String	A required named argument.		✔
optionalArg	String	Another example named argument.
hasDefaultArg	String	Yet another example named argument.	baz

exampleHelloWorld

A trivial step example. See vars/exampleHelloWorld.groovy.

steps {
    exampleHelloWorld()
}

Example build log output:

[Pipeline] echo
Hello, World!

exampleResourceScript

Run a script from the shared library resources as a build step. See vars/exampleResourceScript.groovy and resources/com/example/scripts/example.sh.

steps {
    exampleResourceScript()
}

Example build log output:

[Pipeline] libraryResource
[Pipeline] sh
+ env
+ cut -d = -f 1
+ grep JENKINS
JENKINS_NODE_COOKIE
JENKINS_HOME
JENKINS_URL
JENKINS_SERVER_COOKIE

Contributing

Pull requests are welcome! When adding steps, please add appropriate entries to this document in the Steps section and links in the Introduction list. For major changes, please open an issue to discuss what you'd like to change.