Using Jenkins Shared Libraries: Setup, Usage, and Common Pitfalls

Why Use a Shared Library?

A shared library lets multiple pipelines reuse the same Groovy code, steps, and variables. This centralizes logic, reduces duplication, and makes maintenance easier. Instead of copy‑pasting a long build() function into every Jenkinsfile, you put it once in a library and import it where needed.

Defining the Library in Jenkins

1. Create a Git repository for the library. The repository should contain a src/ folder for classes, a vars/ folder for simple steps, and optionally resources/ for files.

2. In Jenkins, navigate to Manage Jenkins → Configure System → Global Pipeline Libraries.

Field	Description
Name	Unique identifier, e.g., my-lib
Default version	Branch or tag Jenkins should use if none is specified in the job, e.g., main
Source SCM	SCM type (Git) and repository URL
Checkout strategy	How Jenkins checks out the repo (e.g., Branch or tag, Specific revision)
Allow all Groovy in library	Check this if you need unrestricted Groovy code. Otherwise the library runs under the sandbox.

After filling these fields, click Save. Jenkins will now be able to pull the library during pipeline execution.

Importing the Library in a Jenkinsfile

At the top of your Jenkinsfile add the @Library annotation. The syntax is @Library('library-name@branch'). The branch part is optional; if omitted, Jenkins uses the library’s default version.

@Library('my-lib@main') _

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                // Call a step defined in the library
                build()
            }
        }
    }
}

The underscore after the annotation tells Jenkins to import the library into the current context. Once imported, any vars/*.groovy files become callable steps, and src/*.groovy classes can be instantiated.

Example Library Code

In the library repo, create vars/build.groovy:

def call() {
    echo 'Running shared build step'
    sh 'make'
}

Optionally, add a class in src/com/example/Utils.groovy:

package com.example

class Utils {
    static void greet(String name) {
        echo "Hello, ${name}!"
    }
}

Now the Jenkinsfile can use com.example.Utils.greet('world') after importing the library.

Common Pitfalls and How to Avoid Them

• Library Not Added to Global Config: If Jenkins cannot find the library, you’ll see "Could not load library" in the console. Double‑check that the name matches exactly and that the SCM URL is reachable.
• Wrong Branch/Tag: Specifying a non‑existent branch will cause a checkout failure. Use @Library('my-lib@develop') only if develop exists.
• Sandbox Restrictions: By default, library code runs in the Groovy sandbox. Calls like java.lang.Runtime.getRuntime().exec() will throw a SecurityException. Enable "Allow all Groovy in library" or move the library to a trusted workspace.
• Missing Credentials: Hard‑coding secrets in library code is a security risk. Use withCredentials blocks and store secrets in Jenkins credentials.
• Incorrect Checkout Strategy: If you use Specific revision but the SHA changes, the build will fail. Prefer Branch or tag unless you need a fixed commit.

Verifying the Setup

1. Create a minimal library repo with vars/hello.groovy that echoes a message.
2. Configure the library in Jenkins as described.
3. Run a job with a Jenkinsfile that imports the library and calls hello().
4. Check the build console: you should see a line like Loading library my-lib followed by the echoed message.
5. To test sandbox limits, insert a forbidden call in the library and confirm a SecurityException appears.
6. For credentials, bind a secret in Jenkins and reference it via withCredentials in the library; ensure the console does not print the secret.

Version‑Specific Notes

The @Library annotation requires Jenkins 2.5 or newer. On older installations, the annotation is ignored, and the library will not load. Always verify your Jenkins core version before enabling shared libraries.

Conclusion

Shared libraries are a powerful feature for keeping pipelines DRY and maintainable. By correctly configuring the library in Jenkins, importing it with @Library, and paying attention to sandbox and credential best practices, teams can avoid the most common errors and fully leverage reusable pipeline code.