Chapter 25: Shared Libraries, Credentials and Environments

25.3 @Library in the app Jenkinsfile

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

A Flipkart team gets a new microservice, cart-api. The platform team says: use badge-lib. But how exactly should the new Jenkinsfile load it? Some people write @Library at the top. Some use the library step inside script. Some forget the underscore and get a strange error. Some load main in production and break checkout on a Friday. This lesson is about the app side. You will learn every way to write @Library, how to load a branch for testing, how to load two libraries, how to load a library dynamically, and how to make a folder-level library that only one team can see.

What we will build

You will write the cart-api Jenkinsfile in four ways. First, the simple @Library with the default version. Second, a pinned tag. Third, a feature branch of the library for testing a change before merge. Fourth, the library step that loads at run time. You will also set up a folder-level library for the payments team.

What: every term in plain English

• @Library annotation — Loads a library before the pipeline starts. Must be the first line.
• library step — Loads a library during the run, like library('badge-lib@dev'). Good for dynamic versions.
• Implicit load — Library setting that loads it in every job without @Library. Use with care.
• Folder library — A library set on a folder. Only jobs in that folder can use it, and it runs in the sandbox.
• Sandbox — A Groovy safety mode. Unsafe methods need admin approval.
• Version string — After @, a branch, tag or commit id.
• Multiple libraries — @Library(['badge-lib', 'pay-lib@v2']) _ loads two at once.
• Replay — Jenkins feature to edit and rerun a build, including library files, for quick tests.

How: step by step

1. Simplest form

   @Library('badge-lib') _
   

   What it does: Loads the default version set by the admin.

   Output

   Loading library badge-lib@main
   

2. Pinned form

   @Library('badge-lib@v1.4.0') _
   

   What it does: Loads a tag. Best for production.

   Output

   Loading library badge-lib@v1.4.0
   

3. Test a library branch

   @Library('badge-lib@feature/new-scan') _
   

   What it does: Try the library change on one app before merging.

   Output

   Loading library badge-lib@feature/new-scan
   

4. Two libraries

   @Library(['badge-lib@v1.4.0', 'pay-lib@v2.1.0']) _
   

   What it does: Loads both. Steps from both are available.

   Output

   Loading library badge-lib@v1.4.0
   Loading library pay-lib@v2.1.0
   

5. Dynamic load

   library "badge-lib@${params.LIB_VERSION}"
   

   What it does: Loads the version picked in a parameter.

   Output

   Loading library badge-lib@v1.5.0-rc1
   

6. Folder library

   Payments folder > Configure > Pipeline Libraries > Add > name pay-lib
   

   What it does: Only jobs inside Payments can load pay-lib.

   Output

   Saved
   

7. Replay a change

   Build #12 > Replay > edit vars/badgeCi.groovy > Run
   

   What it does: Test a library edit without pushing.

   Output

   Replayed #12
   

Example 1: Write cart-api with a pinned library

Stack. Spring Boot, Maven, Jenkins

Goal. Write cart-api with a pinned library.

cart-api/Jenkinsfile

@Library('badge-lib@v1.4.0') _

badgeCi(
  app: 'cart-api',
  testCmd: 'mvn -B -q test'
)

What each line does

• @Library('badge-lib@v1.4.0') _ — First line. Loads the tag.
• app: 'cart-api' — Image name and labels use this.
• testCmd: 'mvn -B -q test' — cart-api is Java, so it overrides the default npm test.
• No pipeline block — badgeCi builds the whole pipeline.

Green output

Loading library badge-lib@v1.4.0
Checking out Revision 9c3d7e1 (v1.4.0)
[Pipeline] stage (Test)
+ mvn -B -q test
Tests run: 58, Failures: 0, Errors: 0, Skipped: 0
[Pipeline] stage (Build)
+ docker build -t cart-api:7 .
[Pipeline] stage (Scan)
Total: 0 (HIGH: 0, CRITICAL: 0)
Finished: SUCCESS

Expected result. A Java service uses the same shared pipeline with one change.

Example 2: Use your own pipeline and call small library steps

Stack. Jenkins, two shared libraries

Goal. Use your own pipeline and call small library steps.

cart-api/Jenkinsfile

@Library(['badge-lib@v1.4.0', 'pay-lib@v2.1.0']) _
import com.badge.Version

pipeline {
  agent { label 'docker' }
  stages {
    stage('Version') { steps { script { env.V = new Version(this).next() } } }
    stage('Build')   { steps { sh "docker build -t cart-api:${env.V} ." } }
    stage('PCI check') { steps { payPciCheck(image: "cart-api:${env.V}") } }
    stage('Smoke')   { steps { smokeTest('http://10.0.2.15:8080') } }
  }
}

What each line does

• Two libraries in a list — badge-lib for common steps, pay-lib for payment rules.
• import com.badge.Version — Class from badge-lib src.
• payPciCheck — A step from pay-lib vars.
• smokeTest — A step from badge-lib vars.
• Own pipeline — The team keeps control of stage order.

Green output

Loading library badge-lib@v1.4.0
Loading library pay-lib@v2.1.0
[Pipeline] stage (Version)
v1.0.8
[Pipeline] stage (Build)
+ docker build -t cart-api:v1.0.8 .
[Pipeline] stage (PCI check)
PCI: no card data in image layers
[Pipeline] stage (Smoke)
try 1 -> 200
SMOKE OK
Finished: SUCCESS

Expected result. Mixing libraries works. Each team owns its own steps.

Example 3: Pick the library version with a parameter

Stack. Jenkins, parameters, dynamic library

Goal. Pick the library version with a parameter.

cart-api/Jenkinsfile

pipeline {
  agent { label 'docker' }
  parameters {
    string(name: 'LIB_VERSION', defaultValue: 'v1.4.0', description: 'badge-lib tag or branch')
  }
  stages {
    stage('Load') {
      steps {
        script {
          library "badge-lib@${params.LIB_VERSION}"
          sayHello('cart-api')
        }
      }
    }
  }
}

What each line does

• parameters { string ... } — Adds a text box on Build with Parameters.
• library "badge-lib@..." — Loads the library while the build runs.
• script { } — The library step must run inside script in declarative.
• Use case — Platform team tests v1.5.0-rc1 on real apps without changing their files.

Green output

Loading library badge-lib@v1.5.0-rc1
Namaste cart-api from badge-lib
Finished: SUCCESS

Expected result. You tested a release candidate safely on a real app.

Verify: did it work?

1. Confirm the loaded commit

   Console Output > search Checking out Revision
   

   What it does: Shows the exact commit used.

   Output

   Checking out Revision 9c3d7e1 (v1.4.0)
   

2. List folder libraries

   Folder > Configure > Pipeline Libraries
   

   What it does: Shows libraries visible only in that folder.

   Output

   pay-lib  default: v2.1.0
   

When it is red 1

unexpected token: pipeline @ line 2

Cause. The underscore after @Library is missing.

Fix, step by step

1. Change the first line to end with ) _
2. Save and run again.

When it is red 2

Library pay-lib not found

Cause. The job is outside the folder that owns pay-lib.

Fix, step by step

1. Move the job into the Payments folder.
2. Or ask an admin to make it global.

When it is red 3

Scripts not permitted to use method java.io.File list

Cause. Folder libraries run in the sandbox.

Fix, step by step

1. Avoid java.io.File; use sh or findFiles.
2. Or ask an admin to approve in In-process Script Approval if truly needed.

Cleanup

1. Remove the test parameter

   Delete the parameters block and commit
   

   What it does: Production jobs should pin a tag, not take a free text version.

   Output

   Committed
   

Practice tasks

Homework: try at home

Recap

• @Library goes first, with an underscore.
• Pin tags in production.
• Use branches to test library changes.
• The library step loads at run time.
• Folder libraries are private and sandboxed.

FAQ

Should every app pin a version?

Production apps yes. Sandbox apps can follow main.

Can I load by commit id?

Yes, @ followed by the commit id.

Is implicit loading good?

Only for tiny global helpers. It hides where steps come from.

Does Replay change Git?

No. It is only for that one run.

Can a library load another library?

Yes, with the library step inside it, but keep it simple.

Interview questions

1. How does an app Jenkinsfile load a shared library?

   With @Library('name@version') _ at the top, or the library step inside script for dynamic loading.

2. How do you test a library change safely?

   Push a branch, load it with @branch on one app or use Replay, then merge and tag.

3. Global vs folder library?

   Global is trusted and visible everywhere. Folder is sandboxed and visible only in that folder.

4. Why pin library versions?

   So a library change cannot break production builds without review.

5. What does the underscore do?

   It gives the annotation something to attach to when you import nothing else.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards