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.

Practice

1. What does specifying a library version with @version in Jenkins pipelines help achieve?

easy

A. It disables the use of shared libraries in the pipeline.

B. It automatically updates the library to the latest version every time.

C. It ensures the pipeline uses a specific stable version of the shared library.

D. It deletes the library after the pipeline finishes.

Solution

1. Step 1: Understand library versioning purpose

   Library versioning lets you pick a specific version of shared code to keep builds stable.

2. Step 2: Analyze the effect of specifying @version

   Using @version locks the pipeline to that library version, avoiding unexpected changes.

3. Final Answer:

   It ensures the pipeline uses a specific stable version of the shared library. -> Option C

4. Quick Check:

   Library versioning = stable builds [OK]

Hint: Use '@version' to lock library version for stability [OK]

Common Mistakes:

• Thinking '@version' updates to latest automatically
• Believing it disables libraries
• Assuming it deletes libraries after use

2. Which of the following is the correct syntax to load a shared library named utils at version v2.1 in a Jenkins pipeline?

easy

A. library('utils@v2.1')

B. library('utils:v2.1')

C. library('utils#v2.1')

D. library('utils-v2.1')

Solution

1. Step 1: Recall Jenkins library version syntax

   Jenkins uses @ to specify the version or branch of a shared library.

2. Step 2: Match syntax to options

   Only library('utils@v2.1') uses the correct @ symbol for versioning.

3. Final Answer:

   library('utils@v2.1') -> Option A

4. Quick Check:

   Version syntax uses '@' [OK]

Hint: Use '@' to specify library version in library() call [OK]

Common Mistakes:

• Using ':' or '#' instead of '@' for version
• Combining name and version with '-'
• Omitting quotes around library name

3. Given this Jenkins pipeline snippet:

library('commonLib@release-1.0')
node {
  echo commonLib.hello()
}

What will happen if commonLib has a method hello() that returns "Hello v1.0"?

medium

A. The pipeline prints "Hello v1.0".

B. The pipeline prints "Hello latest".

C. The pipeline fails with a method not found error.

D. The pipeline ignores the library and prints nothing.

Solution

1. Step 1: Identify library version used

   The pipeline loads commonLib at version release-1.0.

2. Step 2: Understand method call effect

   Calling commonLib.hello() runs the method from version release-1.0, which returns "Hello v1.0".

3. Final Answer:

   The pipeline prints "Hello v1.0". -> Option A

4. Quick Check:

   Versioned library method returns expected output [OK]

Hint: Versioned library methods return outputs from that version [OK]

Common Mistakes:

• Assuming it prints latest version output
• Expecting a failure without checking version
• Thinking library is ignored without error

4. You wrote this line in your Jenkinsfile:

library('sharedLib@v1.2.3')

But the pipeline fails with an error: Library not found: sharedLib@v1.2.3. What is the most likely cause?

medium

A. The library name sharedLib is misspelled in the Jenkinsfile.

B. The version tag v1.2.3 does not exist in the library repository.

C. The Jenkins server is offline and cannot load any libraries.

D. The pipeline syntax requires double quotes instead of single quotes.

Solution

1. Step 1: Analyze error message

   The error says the library with version v1.2.3 was not found.

2. Step 2: Identify common causes

   This usually means the version tag v1.2.3 does not exist in the library's source repository.

3. Final Answer:

   The version tag v1.2.3 does not exist in the library repository. -> Option B

4. Quick Check:

   Missing version tag causes library not found error [OK]

Hint: Check if version tag exists in library repo when loading fails [OK]

Common Mistakes:

• Assuming syntax quotes cause the error
• Blaming library name spelling without checking version
• Ignoring network or server issues without evidence

5. You want to update your Jenkins pipeline to use a new library version feature-x but keep the old version stable available for some jobs. How can you manage this using Jenkins library versioning?

hard

A. Delete the stable version from the repository to force use of feature-x.

B. Rename the library folder for each version and update the pipeline accordingly.

C. Use library('lib') without version to automatically switch between versions.

D. Specify library('lib@feature-x') in new jobs and library('lib@stable') in old jobs.

Solution

1. Step 1: Understand versioning usage

   Jenkins library versioning lets you specify which version to use per pipeline.

2. Step 2: Apply versioning to different jobs

   By specifying @feature-x or @stable, you control which version each job uses independently.

3. Final Answer:

   Specify library('lib@feature-x') in new jobs and library('lib@stable') in old jobs. -> Option D

4. Quick Check:

   Use '@version' per job to manage multiple library versions [OK]

Hint: Use '@version' per job to switch library versions easily [OK]

Common Mistakes:

• Renaming folders instead of using version tags
• Omitting version to auto-switch versions
• Deleting stable version causing build failures