Working with Pipeline Libraries

1. Defining Shared Libraries

Property	Value	Description
library.name	`my-shared-library`	Name of the shared library to be used in Jenkinsfile
library.retriever	`modernSCM`	Method to retrieve the library code (e.g., Git, SVN)
library.scm	`git`	Source control management system (e.g., git, svn)
library.url	`https://github.com/myorg/my-shared-library.git`	URL to the source repository of the library
library.defaultVersion	`master`	Default branch or tag to use if not specified in Jenkinsfile
library.changelog	`true`	Whether to include changelog in library usage

Example: Defining a Shared Library in Jenkins Configuration

library(
    name: 'my-shared-library',
    retriever: modernSCM(
        type: 'git',
        scm: [
            url: 'https://github.com/myorg/my-shared-library.git'
        ]
    ),
    defaultVersion: 'master',
    changelog: true
)

Note: The library must be defined in Jenkins global configuration or in a folder-level configuration to be accessible across jobs.

2. Configuring Global Libraries

Property	Value	Description
name	`my-library`	Name of the library to be referenced in pipelines
retriever	`modernSCM`	Source control management type (e.g., Git, SVN)
scm	`git`	SCM type to use for retrieving the library code
url	`https://github.com/example/my-library.git`	URL to the Git repository containing the library
credentialsId	`my-git-credentials`	Credentials ID for accessing private repositories (optional)
defaultVersion	`master`	Default branch or tag to use if not specified in pipeline

Example: Global Library Configuration

library(
  name: 'my-library',
  version: '1.0',
  retriever: modernSCM(
    type: 'git',
    scm: git(
      url: 'https://github.com/example/my-library.git',
      credentialsId: 'my-git-credentials'
    )
  )
)

Note: Global libraries must be configured in Jenkins before they can be used in pipelines.

Warning: Ensure that the credentialsId is correctly set for private repositories to avoid access issues.

3. Creating Library Structure

Example: Basic Jenkins Library Directory Layout

my-pipeline-library/
├── vars/
│   └── mySharedFunction.groovy
├── resources/
│   └── myResource.txt
├── src/
│   └── com/
│       └── example/
│           └── MyPipelineStep.groovy
├── tests/
│   └── mySharedFunctionTest.groovy
└── Jenkinsfile

Directory	Description	Usage
vars/	Contains shared Groovy functions accessible in pipelines	Used with `mySharedFunction()` in Jenkinsfile
resources/	Stores files used by shared functions or steps (e.g., templates, config)	Accessed via `resource 'myResource.txt'`
src/	Java or Groovy classes for complex logic or custom steps	Used in `import` statements or step definitions
tests/	JUnit or Pipeline tests for shared functions and steps	Run via `pipeline { tools { ... } }` or `sh 'gradle test'`
Jenkinsfile	Defines how the library itself is built and tested	Used for CI/CD of the library itself

Note: The vars/ directory is required for any shared function to be accessible in pipelines.

Warning: Jenkins libraries must be declared in the Jenkinsfile using library directive to be used in pipelines.

Best Practices for Library Structure

Use vars/ for reusable pipeline functions
Store resources in resources/ to avoid hardcoding paths
Use src/ for complex logic or custom steps
Include tests/ to ensure reliability of shared code
Define a Jenkinsfile for library CI/CD

4. Using Library Functions

Function	Description	Parameters	Example
libraryResource	Loads a resource from the library	`resourcePath` - Path to the resource in the library	`def content = libraryResource 'scripts/common.groovy'`
loadLibrary	Loads a library and makes its functions available	`libraryName` - Name of the library to load	`def lib = loadLibrary 'myLib'`
libraryScript	Executes a script from the library	`scriptPath` - Path to the script in the library	`libraryScript 'scripts/deploy.groovy'`

Example: Using a Library Function

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    def util = loadLibrary 'utility'
                    util.printMessage('Hello from library')
                }
            }
        }
    }
}

Note: Library functions must be defined in a vars directory within the library structure.

5. Versioning Libraries

Version Type	Description	Usage	Notes
Semantic Versioning	Follows `MAJOR.MINOR.PATCH` format	`1.0.0`, `2.1.3`	Recommended for library stability and compatibility
Git Tags	Use Git tags to mark library releases	`git tag v1.2.0`	Used by Jenkins to resolve library versions
Branch-Based Versioning	Use feature branches for development	`release/v2.0`	Allows for parallel development and testing

Example: Using a Specific Version in Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    library version: '1.2.0', changelog: false, implicit: false, optional: false
                }
            }
        }
    }
}

Note: Versioning ensures consistent behavior across builds and avoids unexpected changes from library updates.

6. Loading Dynamic Libraries

Property	Description	Example
library	Defines a dynamic library to be loaded from a Jenkins Shared Library	`library 'my-shared-library@master'`
retriever	Specifies how the library should be retrieved (e.g., Git, SCM)	`retriever git('https://github.com/myorg/mylib.git')`

Example: Loading a Dynamic Library

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                library 'my-shared-library@master'
                sh 'echo "Using shared library"'
            }
        }
    }
}

Note: The library must be defined in Jenkins under Manage Jenkins > Configure Shared Libraries.

Warning: Ensure the library's Jenkinsfile is compatible with your Jenkins version.

7. Using Library Resources

Library resources are files that can be shared across multiple Jenkins pipelines. These resources can include scripts, configuration files, documentation, or any other content that is useful to multiple pipelines.

Resource Type	Description	Usage
resource	Files in the `resources/` directory of a library	Accessed using `libraryResource` step

Example: Using a Library Resource

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                script {
                    def resourceContent = libraryResource resource: 'config.properties'
                    echo "Resource content: ${resourceContent}"
                }
            }
        }
    }
}

Note: The libraryResource step returns the content of the resource as a string. For binary files, consider using libraryResource with appropriate handling or alternative methods.

Key Points

Library resources are stored in the resources/ directory of a Jenkins library.
Access resources using the libraryResource step in a pipeline.
Resources can be used to share configuration files, templates, or other reusable content across pipelines.

8. Testing Pipeline Libraries

Aspect	Description	Notes
Unit Testing	Testing individual functions or components within a library	Use `Jenkins Pipeline Unit Testing Framework` or similar
Integration Testing	Testing how the library integrates with other Jenkins components or pipelines	Use `JUnit` or `Spock` for Groovy-based libraries
End-to-End Testing	Testing the full pipeline flow using the library	Run actual Jenkins jobs to validate behavior

Example: Unit Test a Shared Library Function

import org.jenkinsci.plugins.workflow.cps.CpsScript
import spock.lang.Specification

class MyLibrarySpec extends Specification {
    def "test myFunction"() {
        given:
        def script = new MyLibrary()
        
        when:
        def result = script.myFunction("input")
        
        then:
        result == "expected"
    }
}

Example: Integration Test with Pipeline

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                script {
                    def lib = library(identifier: 'my-lib@master')
                    def result = lib.myFunction("test")
                    echo "Result: ${result}"
                }
            }
        }
    }
}

Note: Ensure that your testing environment mirrors the production Jenkins setup as closely as possible to avoid discrepancies.

9. Documenting Library Functions

Function	Description	Parameters	Return Type
libraryFunction1	Performs a basic operation on input data	`inputData`: String	String
libraryFunction2	Processes a list of items and returns a summary	`items`: List<String>	Map<String, Integer>

Example: Using libraryFunction1

def result = libraryFunction1("example input")
echo "Result: " + result

Example: Using libraryFunction2

def items = ["item1", "item2", "item3"]
def summary = libraryFunction2(items)
echo "Summary: " + summary

Note: Documentation should include examples for each function to help users understand how to use them effectively.

10. Using Multiple Libraries

Library	Variable Name	Usage	Notes
pipeline-library-1	`lib1`	Global shared library for build steps	Loaded via `library` directive in Jenkinsfile
pipeline-library-2	`lib2`	Global shared library for utility functions	Can be imported using `import` in Jenkinsfile

Example: Loading Multiple Libraries in Jenkinsfile

pipeline {
    agent any
    libraries {
        library 'pipeline-library-1@master'
        library 'pipeline-library-2@v1.0'
    }
    stages {
        stage('Build') {
            steps {
                script {
                    lib1.build()
                    lib2.utils()
                }
            }
        }
    }
}

Note: Libraries must be defined in Jenkins global configuration before use.

Warning: Ensure library versions are compatible to avoid runtime errors.