Shared Libraries, Global Variables, vars, src, resources, Versioning, Testing, and Pipeline Product Design: Concepts, Architecture, and Mental Model

1. The reuse problem

By Chapter 23 you can onboard many repositories. If every repository copies the same checkout, test, publish and policy logic, drift becomes inevitable. Jenkins Shared Libraries let teams reuse reviewed Pipeline code from an external SCM repository. The benefit is consistency; the risk is that a single library change can alter dozens or hundreds of builds.

Therefore the unit of control is not just “the Jenkinsfile.” A reproducible build needs a tuple such as consumer SHA + Jenkinsfile path + library name/version/resolved commit + Jenkins/plugin baseline + agent/toolchain. If the library is trusted, its repository write controls are part of Jenkins controller security.

2. Mental model: source to side effect

Read the causal chain before using syntax:

flowchart TD
A[Consumer Jenkinsfile + source SHA] --> B[Library name + requested version]
B --> C[Jenkins library config / trust policy]
C --> D[Modern SCM checkout]
D --> E[Resolved library commit]
E --> F[Compile/load vars + src + resources]
F --> G[Library API call]
G --> H[Pipeline steps on agent/controller]
H --> I[Reports / artifacts / external side effects]
E --> J[Library provenance + compatibility evidence]

The consumer chooses or inherits a version. Jenkins retrieves that version from SCM. Library Groovy is compiled and CPS-transformed for Pipeline use. API calls may orchestrate Pipeline steps, agent work or external systems. Evidence must therefore retain both consumer and library identities.

3. Shared Library repository structure

ch24-lib/
├── vars/
│   ├── buildBanner.groovy
│   └── buildBanner.txt
├── src/
│   └── academy/pipeline/Metadata.groovy
├── resources/
│   └── academy/pipeline/defaults.json
└── README.md

4. Trust is not a convenience checkbox

Global trusted libraries can call APIs that normal sandboxed Pipeline code cannot. Jenkins documentation warns that anyone able to push to a trusted library repository may obtain unlimited access to Jenkins. Configure trusted libraries only when a reviewed use case genuinely needs that power, and protect the SCM accordingly.

Folder-scoped libraries are always untrusted and run in the Groovy sandbox. For most reusable build/test orchestration, that is the safer default. “The sandbox blocked it” is not evidence that the library should become trusted.

5. Version identity and Modern SCM

A configured Shared Library can have a default version and may allow consumers to override it. Git branches, tags and commit hashes can be version selectors. Modern SCM is the preferred retrieval path because Jenkins asks the SCM source for the requested revision directly.

@Library('academy-lib@v1.0.0') _
buildBanner(message: 'compile')

A human-readable tag is useful for release communication; record the resolved commit SHA as immutable evidence. If override is disabled, consumers cannot silently select a different library revision.

6. Read-only state inventory

7. Product discipline

Treat a library release like an internal package: owner, changelog, release/tag policy, review requirements, automated tests, security boundary and rollback. A Shared Library should reduce duplication without hiding the important decisions that belong in a consumer Jenkinsfile—such as privileged deployment authorization or which production environment is targeted.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins — Extending with Shared Libraries — trusted/untrusted libraries, vars/src/resources, version selection, Modern SCM, @Library, library and testing guidance.
• Pipeline: Groovy Libraries — version 805.va_fc79344957d, released 2026-08-27, requiring Jenkins 2.555.1.
• Pipeline: Groovy — version 4380.v6eb_8378b_9647; Shared Library Groovy is CPS-transformed under the same Pipeline execution model.
• Script Security — version 1422.v06869826dd9b_; sandbox and approval boundaries remain security-sensitive.
• Git — version 5.10.1; used by the Modern SCM lab retriever.
• Git Client — version 6.6.1.
• Pipeline Best Practices — avoid overriding built-in Pipeline steps and avoid oversized global-variable files.
• JenkinsPipelineUnit — optional third-party/open-source test framework for Pipeline/library tests; verify the current release and Groovy compatibility before adopting it. The mandatory lab does not require it.
• Pipeline: Deprecated Groovy Libraries — legacy/deprecated plugin; do not use it as the design target for new Shared Libraries.

Version note — 2026-09-17: chapter baseline is Jenkins 2.568.3 LTS with Java 21. The current Pipeline: Groovy Libraries release listed above includes security fixes beyond earlier versions affected by sandbox/file-read/CSRF advisories. Re-check plugin security advisories and the exact SCM/test-tool versions before production rollout.