How to Configure Shared Library in Jenkins for Reusable Pipelines

To configure a shared library in Jenkins, go to Manage Jenkins > Configure System, then add your library under Global Pipeline Libraries by specifying a name and the source repository URL. Use the @Library annotation in your Jenkinsfiles to load and use the shared library functions.

Syntax

The shared library configuration in Jenkins requires these key parts:

• Name: A unique identifier for the library.
• Default version: Branch or tag name to use by default.
• Retrieval method: Usually Git repository URL.
• Load method: How the library is loaded in Jenkinsfiles, typically with @Library('name') _.

groovy

library('my-shared-lib') {
    // Use shared library steps here
}

Example

This example shows how to configure a shared library named my-shared-lib in Jenkins and use it in a Jenkinsfile.

groovy

/* Jenkins Global Configuration (done via UI):
- Name: my-shared-lib
- Default Version: main
- Retrieval Method: Git
- Project Repository: https://github.com/example/my-shared-lib.git
*/

// Jenkinsfile example using the shared library
@Library('my-shared-lib') _

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                script {
                    // Call a function from the shared library
                    mySharedFunction()
                }
            }
        }
    }
}

Output

[Pipeline] Start of Pipeline
[Pipeline] stage
[Pipeline] { (Example)
[Pipeline] script
[Pipeline] {
Calling shared library function: mySharedFunction
[Pipeline] }
[Pipeline] }
[Pipeline] End of Pipeline

Common Pitfalls

Common mistakes when configuring shared libraries include:

• Not setting the library name exactly as used in the Jenkinsfile @Library annotation.
• Forgetting to specify the correct branch or tag in the default version.
• Not granting proper permissions for Jenkins to access the Git repository.
• Using @Library without the trailing underscore _ in the Jenkinsfile, which is required to load the library.

groovy

/* Wrong usage in Jenkinsfile (missing underscore): */
@Library('my-shared-lib')
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                mySharedFunction()
            }
        }
    }
}

/* Correct usage in Jenkinsfile: */
@Library('my-shared-lib') _
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                mySharedFunction()
            }
        }
    }
}

Quick Reference

Configuration Item	Description	Example
Name	Unique library identifier	my-shared-lib
Default Version	Branch or tag to use	main
Retrieval Method	Source control type and URL	Git - https://github.com/example/my-shared-lib.git
Load in Jenkinsfile	Annotation to import library	@Library('my-shared-lib') _
Usage	Call shared functions or vars	mySharedFunction()

Key Takeaways

Configure shared libraries in Jenkins under Manage Jenkins > Configure System > Global Pipeline Libraries.

Use the exact library name with @Library('name') _ annotation in your Jenkinsfile to load the library.

Ensure Jenkins has access permissions to the Git repository hosting the shared library.

Always specify the default version (branch or tag) to avoid unexpected library versions.

Remember the trailing underscore (_) after @Library to properly load the shared library.