Platform Engineering · Lesson 138

Jenkins Shared Libraries: Write One from Scratch

Lesson 111 showed you a Jenkinsfile that calls a shared library with one line. This lesson is the one where you write the library. A repo holds the shared code. The vars folder holds the steps every pipeline calls. The src folder holds the classes. By the end you have built a library, versioned it, tested it, and watched twenty pipelines use it.

Difficulty: Advanced · Know this first: Lesson 111 — Jenkins

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenario — not a measurement from a live system — but the shape is honest: on a cache hit the trip is almost free, on a miss the kitchen eats the budget. Step through the lesson or switch the scenario and watch the bar change.

Extra diagram · from scratch to master

The library, mapped: repo, vars, src, test

Start with one copied stage. Add one box at a time until twenty pipelines share one library, test included.

7 boxes on the trip20 pipelines1 broken build
Copied stage
0 min
Library repo
1 min
vars/
2 min
src/
2 min
@Library
1 min
Test
4 min
Broken build
trip ends
Request / flowResponse · the way backFailure / dead end

Try it: change the inputs and watch the trip bend

The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the library code, the tests, and the rollout change in the budget bar, in the hop timings, and in the total. The numbers are a teaching example, not live measurements. The shape is the lesson: sharing multiplies the value of one fix, and it multiplies the blast radius of one mistake.

20

How many pipelines load the same library version. Every pipeline adds its own rollout run. The library is written once. The runs are paid once per pipeline.

5

How many steps the vars folder holds. Each step costs about a minute to load and check, in every pipeline that uses the library.

10

How many unit tests check the library classes. Each test costs about a minute, and the tests run once, before any pipeline uses the change.

Try this: (1) Set pipelines to 30, steps to 10, tests to 20. The library code is about 10 min, the tests about 20 min, the rollout about 30 min, and the total is about 66 min. (2) Set all three to the worst end: 50 pipelines, 20 steps, 30 tests. The library code is 20 min, the tests are 30 min, the rollout is 50 min, and the total is about 106 min. Same library. Only the inputs changed.

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Try it: edit the pipeline and check it

Here is a Jenkinsfile that loads a shared library and calls its deploy step. Change it, then run the check. The check looks for the three things this lesson teaches: the @Library line with a pinned version, a pipeline block, and a call to the shared deploy step.

Try breaking it on purpose: delete the version after the @ sign, or rename the deployApp call to something else. Run the check and watch it fail. Then press Reset and try a change that keeps it passing, like adding a second stage that calls the shared step.

Press "Run the check" to see whether this pipeline does what the lesson asks.

Expected output when it passes: The Jenkinsfile loads the pinned library, declares a pipeline, and calls the shared deploy step. This pipeline would run the shared deploy.

Basic to master

I take the same library four times here. First I learn the folders. Then I learn versions and tests. Then I learn the rollout. Last I run it for the world.

Basic — vars, src, and one call

Definition: A shared library is a repo with two folders. Vars holds the steps pipelines call, one file per step. Src holds the classes those steps use. A Jenkinsfile loads the library with @Library, naming the library and the version, and calls a step by name.

Types:

  • A vars file, which is a step named by the file.
  • A src class, which does the work the step calls.
  • An @Library line, which loads the library into the pipeline.
  • A version tag, which says which code the pipeline loads.

Uses: I use this when two Jenkinsfiles have the same deploy stage and I am tired of fixing the same bug twice. I move the stage into the library, call it from both files, and fix it once. Try it now: write a Jenkinsfile that loads the library in the Try it box, and run the check.

Dimensions: At low traffic everything is nearly free. What breaks first is the unpinned version: a library change lands in your pipeline on the next run, and you did not ask for it. It costs one version tag to pin it. It costs a broken build when you skip it.

Intermediate — Versions, tests, and thin steps

Definition: The library repo gets tags and a changelog. A breaking change ships as a new major version. The classes in src get unit tests that run without Jenkins. The vars files stay thin, under twenty lines, and call the classes. A test pipeline loads the library and runs a scratch Jenkinsfile against it before the tag ships.

Types:

  • Tags, which mark a release like 2.4.0.
  • Unit tests, which check the src classes without Jenkins.
  • A test pipeline, which loads the library before the tag ships.
  • A changelog, which says what changed in each release.

Uses: I use tags so no pipeline is forced onto a breaking change. I use unit tests so a bad class never ships. I use a test pipeline so a bad vars step never ships. Try it now: break the class on purpose in your head, and name which test would catch it. If no test would catch it, that test does not exist yet.

Dimensions: As the library grows, the steps grow, and the test suite grows with them. What breaks is the vars file that grew past twenty lines, because the logic never moved to src. It costs a move, not a rewrite.

Advanced — Rollouts and trust

Definition: A library version rolls out one pipeline at a time. A version that breaks one pipeline is a lesson. A version that breaks twenty at once is an outage. The library repo gets owners, a CODEOWNERS file, and a review rule. A dashboard shows which pipelines pin which version, so a bad version can be found in one look.

Types:

  • A staged rollout, one pipeline at a time.
  • CODEOWNERS, which says who must approve a library change.
  • A version dashboard, which shows every pipeline and its pinned version.
  • A rollback, which is one @Library line change back to the old tag.

Uses: I use a staged rollout so a bad version hurts one pipeline, not twenty. I use CODEOWNERS so a library change gets a second pair of eyes. I use the dashboard so a bad version can be found in one look. Lesson 139 builds the downstream chains on top of this.

Dimensions: At ten times the pipelines, the version is the lesson. What breaks is the library change that twenty pipelines did not expect. It costs a test pipeline and a changelog. The trade is that sharing is powerful and unforgiving in the same breath.

The step that broke twenty pipelines. A shared step is a library, and a library change reaches every caller. I test the step the way I test code: a pipeline that calls it in a test repo, before the change ships to the real callers.

Do this: change a shared step in a test branch of the library repo, and point one test pipeline at that branch with the @Library line from the snippet. Expected: the test pipeline uses the new step and the real pipelines keep the old one. A green test pipeline is the permission to merge.

@Library("pipeline-library@test-branch") _

What the snippet means: the @Library line pins the version a pipeline loads. A test branch lets one pipeline try the change while the rest of the org stays on the release.

The global variable that hid a bug. A vars step is global, and a global step with a bad default breaks every caller that does not pass the value. I give shared steps no silent defaults for anything that matters. A missing value fails loudly, at the call, with the name of the missing input.

Do this: call a shared step without a required argument and read the error. Expected: the error names the missing argument and the line that called it. Add an explicit check at the top of the step that fails with a plain message when the argument is missing, and call it again. Expect the same failure, now in words a caller can act on.

def call(Map config) {
  if (!config.environment) {
    error "deployApp needs an environment: deployApp(environment: 'staging')"
  }
}

What the snippet means: the check at the top turns a confusing failure three lines down into a plain message at the call. A shared step that fails clearly is a step people trust.

Master — The library as a platform

Definition: At this level the library is a platform with owners, versions, tests, and a deprecation policy. Old versions get a sunset date. Breaking changes ship with a migration guide. A dashboard shows which pipelines pin which version. And I rehearse the worst day: the library repo is down, and no pipeline can load it.

Types:

  • A deprecation policy, which says when an old version stops working.
  • A version dashboard, which shows every pipeline and its pinned version.
  • A migration guide, which ships with every major version.
  • A fallback plan, for the day the library repo cannot be reached.

Uses: I use this when more than one team ships through the same library, or when a bad library can take down services other teams depend on. It is also how I review a setup I did not build: I ask where the library lives, who can change it, and what happens when it is gone. Try it now: pick one shared step you own and write its sunset date. If it has none, it has no owner.

Dimensions: At a hundred times the pipelines, the library repo is not the bottleneck, the blast radius is. What breaks is the single library that everything depends on, or the version nobody can find. It costs real operational work: owners, tests, dashboards, and drills.

The library repo is down. Every pipeline loads the library from the repo. When the repo is down, no pipeline can load it, and no pipeline runs. I rehearse that day on purpose, in business hours, so the first time it happens is not at 2 AM.

Do this: point a test pipeline at a library branch that does not exist and run it. Expected: the pipeline fails before any stage runs, with an error that names the library. That is the blast radius, written down. The fallback is a mirror of the library repo, and the drill is switching the @Library line to the mirror and watching the pipeline run.

@Library("pipeline-library@mirror") _

What the snippet means: the @Library line is the only thing that changes in the fallback. A mirror that nobody has tested is not a fallback, it is a hope.

The version dashboard, built from the code. A bad library version is found by asking every caller which version it pins. I do not ask the teams. I search the repos. A dashboard is a search result, kept current, and the bad version is found in one look.

Do this: search your repos for the @Library line with the command in the snippet. Expected: a list of repos and the version each one pins. A repo that pins an old version is a repo that needs a bump, and the list is the work, in order.

grep -r "@Library" --include=Jenkinsfile . | sort

What the snippet means: the grep is the dashboard. Every @Library line names the version its pipeline loads, and the list shows which pipelines a bad version reaches.

Read the flags: grep -r --include=Jenkinsfile and sort

A bad library version is found by asking every caller which version it pins. I do not ask the teams. I search the repos.

  • grep -r: The -r flag searches files under a directory, not one file. Without it, grep would complain that the dot is a directory and search nothing.
  • "@Library": This is the text to find. Every Jenkinsfile that loads a shared library has this line, and the line names the version it pins.
  • --include=Jenkinsfile: This limits the search to files named Jenkinsfile. Without it, grep would also search READMEs and docs, and the list would be full of mentions instead of real loads.
  • . (the dot): This is the directory to search, the current one. It means start here and go down through every subfolder.
  • | sort: The pipe hands the matches to sort. Sort orders them alphabetically, so the same version groups together and the odd one out is easy to spot.
  • grep -n (added): The lesson did not show this one yet. It prints the line number with each match. I use it when I need to open the Jenkinsfile at the match and change the version.

Try it: search your repos for the @Library line with the command in the snippet. Expect a list of repos and the version each one pins. A repo that pins an old version is a repo that needs a bump.

Go deeper

Start with the vars step, then the class, then the Jenkinsfile that calls it. The vars step below is thin on purpose: it takes an environment name and hands the work to a class. Do this: save it as vars/deployApp.groovy in a repo called pipeline-library, count its lines, and check the braces balance. Expected output: fewer than twenty lines, and every opening brace has a closing brace.

def call(String environment) {
  def deployer = new com.shop.Deployer(this)
  deployer.deploy(environment)
}

What the snippet means: the step is four lines. It builds a Deployer from the src folder and calls deploy with the environment name. The step knows nothing about how the deploy works. That is the point.

The class does the work. Do this: save the class below as src/com/shop/Deployer.groovy in the same repo, and check the braces balance the same way. Expected output: the class builds the deploy command from the environment name, and a test can call it without Jenkins.

package com.shop

class Deployer implements Serializable {
  def steps
  Deployer(steps) { this.steps = steps }
  def deploy(String environment) {
    steps.sh "make deploy ENV=${environment}"
  }
}

What the snippet means: the class holds the steps object, takes the environment name, and runs one shell command with it. It is plain code, so a unit test can build it with a fake steps object and check the command it builds.

The Jenkinsfile is short, because the library does the work. Do this: save the file below as Jenkinsfile in a scratch repo, check the braces balance, and push it. Expected output: the pipeline loads version 2.4.0 of the library, runs the build and the test, and calls the shared deploy step.

@Library('platform-pipeline@2.4.0') _

pipeline {
  agent { label 'build' }
  stages {
    stage('Build') {
      steps { sh 'make build' }
    }
    stage('Test') {
      steps { sh 'make test' }
    }
    stage('Deploy') {
      steps { deployApp('production') }
    }
  }
}

What the snippet means: one line loads the library, and one line calls the shared step. The pipeline owns the order. The library owns the deploy.

At 10x the pipelines, the shape holds and the numbers grow. At 100x, the design changes: the library gets owners, tests, a version dashboard, and a deprecation policy. The library never stops being shared code. It just gets more callers, and more ways to break them. The next lesson in this track chains pipelines together.

A breaking change with a migration guide

A major version of a shared step breaks its callers on purpose. The break is fine. The break without a guide is not. I ship the migration guide with the version, and I test the guide by migrating one caller with it.

Do this: pick a shared step and write a two-line migration guide for its next major version: the old call and the new call. Migrate one caller with the guide and run its pipeline. Expected: the pipeline passes. If the guide misses a step, the pipeline fails, and the guide is wrong, not the caller. Fix the guide, not the caller.

// v1: deployApp('staging')
// v2: deployApp(environment: 'staging', dryRun: false)
def call(Map config) {
  echo "Deploying to ${config.environment}"
}

What the snippet means: the old call and the new call sit side by side in the guide. A caller that follows the guide exactly should pass first time, and a guide that fails its first caller is a draft.

One time it broke

What broke

A library change I shipped broke twenty pipelines at once. The Jenkinsfiles pinned a branch name, not a tag, so every pipeline loaded the newest library on its next run. I renamed a vars step, and twenty pipelines failed with a step-not-found error within the hour. The library did exactly what it was told. Nobody had told it to stay still.

Timeline

  • 09:12,I renamed a vars step in the library repo and pushed to the main branch, to clean up a name I did not like.
  • 09:20,the first pipeline ran. It failed: the step name it called no longer existed.
  • 09:35,nineteen more pipelines failed the same way, each on its next run. Twenty teams asked what had changed.
  • 09:50,I reverted the rename, tagged the library 2.4.0, and pinned the version in all twenty Jenkinsfiles.
  • 10:15,all twenty pipelines were green again. The rename shipped a week later as 3.0.0, with a note in the changelog.

What changed after

Three things. First, every @Library line pins a tag, and a pin to a branch name is treated as broken in review. Second, the library repo gets a tag and a changelog for every release. Third, a library change runs a test pipeline before it ships. Try it now: open any @Library line you own and read what follows the @ sign. If it is a branch name, pin it before the next run.

If you remember nothing else

Build it yourself

Build a shared library with a vars step, a src class, and a Jenkinsfile that uses both. The vars step must be thin and call the class. The class must build the deploy command from the environment name. The Jenkinsfile must load the library at a pinned version and call the step. It passes when the pipeline turns green, and when a test that breaks the class on purpose goes red.

Build it, step by step

  • Create a repo called pipeline-library with folders vars and src, and a README that says what the library is for.
  • Write vars/deployApp.groovy as a thin step that builds a Deployer from src and calls deploy with the environment name.
  • Write src/com/shop/Deployer.groovy as a class that runs the deploy command with the environment name.
  • Write a test that calls the Deployer with a fake steps object and checks the command it builds, then break the class on purpose and confirm the test goes red.
  • Write a Jenkinsfile that loads the library at version 2.4.0 and calls deployApp('production'), push it, and confirm the pipeline turns green.

What success looks like

Success looks like this: the vars file is under twenty lines and the braces balance. The test passes on the good class and fails on the broken class. The pipeline loads version 2.4.0, runs the build and the test, and calls the shared deploy step, and the app serves the new code.

If it fails, check this

If the pipeline fails with a step-not-found error, the vars file name and the call do not match. If the library loads the wrong code, the version after the @ sign is a branch name. If the test never fails, it checks nothing. If the vars file is long, the logic has not moved to src.

Next in this series
Lesson 139 — Jenkins Downstream Builds and Multibranch Pipelines