Library versioning in Jenkins - Commands & Configuration

Introduction

Library versioning in Jenkins helps you manage different versions of shared code libraries used in your pipelines. This solves the problem of keeping your pipeline code stable and consistent while allowing updates and improvements to libraries without breaking existing jobs.

When you want to reuse common pipeline code across multiple Jenkins jobs safely.

When you need to update a shared library but want to test changes before applying them everywhere.

When different projects require different versions of the same shared library.

When you want to roll back to a previous library version if a new one causes issues.

When you want to track and control which library version each pipeline uses.

Config File - Jenkinsfile

Jenkinsfile

@Library('my-shared-lib@v1.2.0') _
pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                script {
                    mySharedLibFunction()
                }
            }
        }
    }
}

def mySharedLibFunction() {
    echo 'Running shared library version 1.2.0'
}

This Jenkinsfile uses the @Library annotation to load a specific version (v1.2.0) of a shared library named my-shared-lib. The @v1.2.0 suffix specifies the exact version to use. Inside the pipeline, it calls a function from that library. This ensures the pipeline uses a stable, tested library version.

Commands

Check the installed Jenkins Job Builder version to ensure Jenkins CLI tools are available.

Terminal

jenkins-jobs --version

Expected Output

1.0.0

Clone the shared library repository to your local machine to manage versions with Git tags.

Terminal

git clone https://github.com/example/my-shared-lib.git

Expected Output

Cloning into 'my-shared-lib'...

remote: Enumerating objects: 10, done.

remote: Counting objects: 100% (10/10), done.

remote: Compressing objects: 100% (8/8), done.

remote: Total 10 (delta 1), reused 10 (delta 1), pack-reused 0

Receiving objects: 100% (10/10), done.

Resolving deltas: 100% (1/1), done.

Create and push a Git tag named v1.2.0 to mark the stable library version for Jenkins to use.

Terminal

cd my-shared-lib && git tag v1.2.0 && git push origin v1.2.0

Expected Output

Total 0 (delta 0), reused 0 (delta 0)

To https://github.com/example/my-shared-lib.git

 * [new tag]         v1.2.0 -> v1.2.0

Trigger the Jenkins pipeline job that uses the shared library version v1.2.0 to verify it runs correctly.

Terminal

jenkins-cli build my-pipeline

Expected Output

Started build #15

Building in workspace /var/lib/jenkins/workspace/my-pipeline

[Pipeline] Start of Pipeline

Running shared library version 1.2.0

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: specifying library versions in Jenkins pipelines ensures stable, repeatable builds and safe updates.

Common Mistakes

Not specifying a library version and always using the latest code.

This can cause unexpected pipeline failures if the library changes in incompatible ways.

Always specify a fixed library version using the @version syntax to lock the pipeline to a tested library state.

Tagging the library version locally but forgetting to push the tag to the remote repository.

Jenkins cannot fetch the version tag and will fail to load the specified library version.

After creating a Git tag, always push it to the remote repository with 'git push origin <tag>'.

Summary

Use the 'library' step with '@version' to specify the exact shared library version in Jenkins pipelines.

Manage library versions with Git tags pushed to the remote repository.

Trigger pipeline builds to verify the correct library version is used and working.