Loading libraries in Jenkinsfile - Commands & Configuration

Introduction

Sometimes you want to reuse code in Jenkins pipelines to keep things simple and organized. Loading libraries in a Jenkinsfile lets you share common steps or functions across many pipelines without repeating yourself.

When you have multiple Jenkins pipelines that need to run similar steps like building or testing.

When you want to update a shared function once and have all pipelines use the new version automatically.

When you want to keep your Jenkinsfiles short and clean by moving complex logic to libraries.

When you want to share helper functions or variables between different Jenkins projects.

When you want to organize your pipeline code better for easier maintenance.

Config File - Jenkinsfile

Jenkinsfile

@Library('my-shared-library') _

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

This Jenkinsfile loads a shared library named my-shared-library using the @Library annotation.

The pipeline block defines the pipeline stages and steps.

Inside the script block, it calls a function mySharedFunction() that is defined in the shared library.

This setup lets you reuse code from the shared library in your pipeline.

Commands

Check that Jenkins Job Builder CLI is installed and working before creating Jenkinsfiles.

Terminal

jenkins-jobs --version

Expected Output

3.10.0

Clone the shared library repository to your local machine or Jenkins server to prepare for use.

Terminal

git clone https://github.com/jenkinsci/my-shared-library.git

Expected Output

Cloning into 'my-shared-library'...

remote: Enumerating objects: 10, done.

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

remote: Compressing objects: 100% (7/7), 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.

Push your Jenkinsfile that loads the shared library to your Jenkins pipeline repository.

Terminal

git push origin main

Expected Output

Enumerating objects: 3, done.

Counting objects: 100% (3/3), done.

Delta compression using up to 8 threads

Compressing objects: 100% (2/2), done.

Writing objects: 100% (3/3), 300 bytes | 300.00 KiB/s, done.

Total 3 (delta 0), reused 0 (delta 0), pack-reused 0

To https://github.com/your-org/your-pipeline.git

   abc1234..def5678  main -> main

Trigger the Jenkins pipeline that uses the shared library to verify it loads and runs correctly.

Terminal

jenkins-cli build your-pipeline

Expected Output

Started build #15

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

[Pipeline] Start of Pipeline

[Pipeline] library

Loading library my-shared-library

[Pipeline] mySharedFunction

Executing shared function

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: loading a shared library in Jenkinsfile lets you reuse and organize pipeline code across projects.

Common Mistakes

Not configuring the shared library in Jenkins global settings before using it in Jenkinsfile.

Jenkins cannot find the library and the pipeline fails to load it.

Go to Jenkins > Manage Jenkins > Configure System > Global Pipeline Libraries and add the library with the correct name and repository.

Calling library functions outside a script block in declarative pipeline.

Declarative pipelines require script blocks to run Groovy code, so the call fails.

Wrap calls to shared library functions inside a <code>script { }</code> block.

Using the wrong library name in the Jenkinsfile that does not match the configured library name.

Jenkins cannot find the library and throws an error.

Use the exact library name as configured in Jenkins global settings.

Summary

Use the @Library annotation in Jenkinsfile to load shared libraries by name.

Configure shared libraries in Jenkins global settings before using them.

Call shared library functions inside script blocks in declarative pipelines.

Push Jenkinsfile and shared library code to their repositories and trigger builds to test.

Practice

1. What is the main purpose of loading libraries in a Jenkinsfile?

easy

A. To automatically update Jenkins plugins

B. To reuse common pipeline code across multiple Jenkinsfiles

C. To increase the build speed by caching dependencies

D. To create new Jenkins jobs dynamically

Solution

1. Step 1: Understand the role of libraries in Jenkinsfiles

   Libraries contain reusable pipeline code that can be shared across multiple Jenkinsfiles.

2. Step 2: Identify the benefit of using libraries

   Using libraries helps keep Jenkinsfiles clean and avoids code duplication by reusing common code.

3. Final Answer:

   To reuse common pipeline code across multiple Jenkinsfiles -> Option B

4. Quick Check:

   Libraries = Reuse code [OK]

Hint: Libraries help reuse code, not speed or plugins [OK]

Common Mistakes:

• Confusing libraries with plugin management
• Thinking libraries speed up builds directly
• Assuming libraries create jobs automatically

2. Which of the following is the correct syntax to load a shared library named 'utils' at version '1.2' in a Jenkinsfile?

easy

A. loadLibrary('utils', '1.2')

B. useLibrary utils version 1.2

C. import 'utils:1.2'

D. library 'utils@1.2'

Solution

1. Step 1: Recall the Jenkinsfile syntax for loading libraries

   The correct syntax uses the keyword library followed by the library name and version in quotes, separated by '@'.

2. Step 2: Match the syntax to the options

   library 'utils@1.2' matches the correct syntax: library 'utils@1.2'.

3. Final Answer:

   library 'utils@1.2' -> Option D

4. Quick Check:

   library 'name@version' = correct syntax [OK]

Hint: Use library 'name@version' format to load libraries [OK]

Common Mistakes:

• Using incorrect keywords like loadLibrary or import
• Missing quotes around the library name and version
• Using spaces instead of '@' between name and version

3. Given this Jenkinsfile snippet:

library 'common@2.0'
pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        script {
          echo common.hello()
        }
      }
    }
  }
}

What will happen when this pipeline runs if the 'common' library has a method hello() that returns 'Hello from common library'?

medium

A. The pipeline will print 'Hello from common library' in the console output

B. The pipeline will fail with a method not found error

C. The pipeline will print 'common.hello()' as a string

D. The pipeline will skip the 'Test' stage silently

Solution

1. Step 1: Understand library loading and method call

   The library 'common@2.0' is loaded, so its methods like hello() are available in the Jenkinsfile.

2. Step 2: Analyze the echo statement

   The echo command calls common.hello(), which returns the string 'Hello from common library', so this string will be printed.

3. Final Answer:

   The pipeline will print 'Hello from common library' in the console output -> Option A

4. Quick Check:

   Loaded library method call prints returned string [OK]

Hint: Loaded library methods return values usable in pipeline [OK]

Common Mistakes:

• Assuming method calls fail without explicit import
• Thinking echo prints code literally
• Expecting silent skip without error

4. You wrote this Jenkinsfile snippet:

library 'tools@latest'
pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        script {
          tools.build()
        }
      }
    }
  }
}

But the pipeline fails with an error: groovy.lang.MissingPropertyException: No such property: tools. What is the likely cause?

medium

A. The agent 'any' is not supported in this Jenkins version

B. The method build() does not exist in the tools library

C. The library 'tools' is not configured or not loaded properly

D. The Jenkinsfile syntax for stages is incorrect

Solution

1. Step 1: Understand the error message

   The error says 'No such property: tools', meaning the variable or library named 'tools' is not recognized in the pipeline.

2. Step 2: Identify the cause related to library loading

   This usually happens if the shared library 'tools' is not configured in Jenkins or the library failed to load, so the variable 'tools' is undefined.

3. Final Answer:

   The library 'tools' is not configured or not loaded properly -> Option C

4. Quick Check:

   MissingPropertyException means library not loaded [OK]

Hint: MissingPropertyException means library not loaded or configured [OK]

Common Mistakes:

• Assuming method build() missing causes this error
• Blaming pipeline syntax for this error
• Thinking agent 'any' causes this error

5. You want to load two shared libraries in your Jenkinsfile: 'utils' at version '1.0' and 'deploy' at version '2.1'. Which Jenkinsfile snippet correctly loads both libraries and calls a method deployApp() from the 'deploy' library inside a stage?

hard

A. library 'utils@1.0'
library 'deploy@2.1'
pipeline {
agent any
stages {
stage('Deploy') {
steps {
script {
deploy.deployApp()
}
}
}
}
}

B. libraries {
utils '1.0'
deploy '2.1'
}
pipeline {
agent any
stages {
stage('Deploy') {
steps {
script {
deploy.deployApp()
}
}
}
}
}

C. library 'utils@1.0,deploy@2.1'
pipeline {
agent any
stages {
stage('Deploy') {
steps {
script {
deployApp()
}
}
}
}
}

D. library 'utils@1.0'
library 'deploy@2.1'
pipeline {
agent any
stages {
stage('Deploy') {
steps {
script {
deployApp()
}
}
}
}
}

Solution

1. Step 1: Load multiple libraries separately

   Each library must be loaded with its own library 'name@version' statement; library 'utils@1.0' library 'deploy@2.1' pipeline { agent any stages { stage('Deploy') { steps { script { deploy.deployApp() } } } } } correctly loads 'utils@1.0' and 'deploy@2.1' separately.

2. Step 2: Call method from the correct library namespace

   To call deployApp() from 'deploy' library, use deploy.deployApp() inside the script block, as shown in library 'utils@1.0' library 'deploy@2.1' pipeline { agent any stages { stage('Deploy') { steps { script { deploy.deployApp() } } } } }.

3. Final Answer:

   Option A correctly loads both libraries and calls deploy.deployApp() -> Option A

4. Quick Check:

   Separate library calls + qualified method call = library 'utils@1.0' library 'deploy@2.1' pipeline { agent any stages { stage('Deploy') { steps { script { deploy.deployApp() } } } } } [OK]

Hint: Load each library separately; call methods with library name prefix [OK]

Common Mistakes:

• Trying to load multiple libraries in one statement
• Calling methods without library prefix
• Using incorrect syntax like 'libraries' block