@Library annotation in Jenkins - Commands & Configuration

Introduction

When you want to reuse code in Jenkins pipelines, the @Library annotation helps you load shared libraries easily. It solves the problem of copying the same code in many pipelines by letting you keep common functions in one place.

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

When you want to keep your pipeline code clean by moving complex logic to shared libraries.

When you want to update common pipeline code in one place and have all pipelines use the new version.

When you want to share pipeline code across different teams or projects in Jenkins.

When you want to use community or custom Jenkins libraries to add extra features to your pipelines.

Commands

This command creates a Jenkinsfile that uses the @Library annotation to load the shared library named 'my-shared-lib' at version 'v1'. The underscore means to import all the library's global vars and steps.

Terminal

echo "@Library('my-shared-lib@v1') _" > Jenkinsfile

Expected Output

No output (command runs silently)

This command shows the content of the Jenkinsfile to verify the @Library annotation is correctly added.

Terminal

cat Jenkinsfile

Expected Output

@Library('my-shared-lib@v1') _

This command tests the Jenkinsfile syntax including the @Library annotation to ensure it is valid before running the pipeline.

Terminal

jenkins-jobs --conf jenkins.ini test Jenkinsfile

Expected Output

INFO:jenkins_jobs.builder:Parsing Jenkinsfile

INFO:jenkins_jobs.builder:Validation successful

Key Concept

If you remember nothing else from this pattern, remember: the @Library annotation lets you load shared pipeline code easily to reuse and keep your Jenkins pipelines simple.

Common Mistakes

Forgetting to add the underscore (_) after the @Library annotation

Without the underscore, Jenkins does not import the library's global variables and steps, so your pipeline cannot use them.

Always add an underscore after the @Library annotation like @Library('lib-name@version') _ to import the library correctly.

Using a library name or version that does not exist in Jenkins configuration

Jenkins will fail to load the library and the pipeline will error out because it cannot find the specified library.

Make sure the shared library is configured in Jenkins with the exact name and version you use in the annotation.

Summary

Use the @Library annotation in Jenkinsfiles to load shared pipeline libraries.

Add an underscore (_) after the annotation to import all library steps and variables.

Verify your Jenkinsfile syntax before running pipelines to catch errors early.

Practice

1. What is the main purpose of the @Library annotation in Jenkins pipelines?

easy

A. To specify the pipeline agent type

B. To load shared code libraries for reuse in pipelines

C. To define environment variables for the pipeline

D. To trigger downstream jobs automatically

Solution

1. Step 1: Understand the role of @Library

   The @Library annotation is used to load shared libraries in Jenkins pipelines.

2. Step 2: Identify its main purpose

   Loading shared libraries allows reuse of code and better organization of pipeline scripts.

3. Final Answer:

   To load shared code libraries for reuse in pipelines -> Option B

4. Quick Check:

   @Library loads shared libraries = C [OK]

Hint: Remember: @Library loads reusable code libraries [OK]

Common Mistakes:

• Confusing @Library with environment variable setup
• Thinking it triggers jobs instead of loading code
• Using it to specify pipeline agents

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

easy

A. @Library('utils') _

B. @Library utils _

C. library('utils') _

D. @LoadLibrary('utils') _

Solution

1. Step 1: Recall the correct syntax for @Library

   The correct syntax uses parentheses and quotes around the library name, followed by an underscore.

2. Step 2: Match the syntax to options

   @Library('utils') _ matches @Library('utils') _, which is correct.

3. Final Answer:

   @Library('utils') _ -> Option A

4. Quick Check:

   Correct syntax uses parentheses and underscore = A [OK]

Hint: Use parentheses and underscore after @Library [OK]

Common Mistakes:

• Omitting parentheses or quotes
• Using wrong annotation like @LoadLibrary
• Placing underscore before the annotation

3. Given this Jenkinsfile snippet:

@Library('mathLib') _
pipeline {
  agent any
  stages {
    stage('Calculate') {
      steps {
        script {
          echo mathLib.add(2, 3).toString()
        }
      }
    }
  }
}

What will be the output if the shared library 'mathLib' has a method add(a, b) that returns the sum of two numbers?

medium

A. 5

B. mathLib.add(2, 3)

C. Error: method not found

D. 23

Solution

1. Step 1: Understand the method call in the script block

   The code calls mathLib.add(2, 3) which returns the sum of 2 and 3.

2. Step 2: Convert the result to string and echo

   The result 5 is converted to string and printed by echo.

3. Final Answer:

   5 -> Option A

4. Quick Check:

   Sum of 2 and 3 = 5 [OK]

Hint: Method returns sum; echo prints '5' as string [OK]

Common Mistakes:

• Expecting the method name printed instead of result
• Confusing concatenation with addition
• Assuming method is missing causing error

4. You wrote this at the top of your Jenkinsfile:

@Library('commonLib')
pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        script {
          commonLib.doSomething()
        }
      }
    }
  }
}

But Jenkins throws an error saying Missing required underscore after @Library annotation. How do you fix it?

medium

A. Change @Library to @LoadLibrary

B. Remove the parentheses from @Library

C. Place the underscore before the annotation like _ @Library('commonLib')

D. Add an underscore _ immediately after the annotation like @Library('commonLib') _

Solution

1. Step 1: Identify the syntax error from the message

   The error says the underscore is missing after @Library, which is required syntax.

2. Step 2: Correct the syntax by adding underscore

   Add an underscore immediately after the annotation: @Library('commonLib') _.

3. Final Answer:

   Add an underscore _ immediately after the annotation like @Library('commonLib') _ -> Option D

4. Quick Check:

   Underscore after @Library fixes syntax [OK]

Hint: Always put underscore right after @Library(...) [OK]

Common Mistakes:

• Omitting the underscore
• Placing underscore before annotation
• Changing annotation name incorrectly

5. You want to load two shared libraries named 'utils' and 'helpers' in your Jenkinsfile. Which is the correct way to do this using the @Library annotation?

hard

A. @Library('utils_helpers') _

B. @Library('utils') _ @Library('helpers') _

C. @Library(['utils', 'helpers']) _

D. @Library('utils,helpers') _

Solution

1. Step 1: Recall how to load multiple libraries

   Multiple libraries can be loaded by passing a list of names inside @Library annotation.

2. Step 2: Identify correct syntax for multiple libraries

   The correct syntax is @Library(['utils', 'helpers']) _ which loads both libraries at once.

3. Final Answer:

   @Library(['utils', 'helpers']) _ -> Option C

4. Quick Check:

   Use list inside @Library for multiple libs [OK]

Hint: Use list syntax inside @Library to load many libs [OK]

Common Mistakes:

• Trying to use multiple @Library annotations
• Passing comma-separated string instead of list
• Combining names into one string without list