Shared Libraries, Global Variables, vars, src, resources, Versioning, Testing, and Pipeline Product Design: Diagnostics, Failure Modes, Security, and Performance

1. Evidence-first diagnostic sequence

1. Preserve job/build/queue IDs, console output and the exact first error.
2. Record Jenkins LTS/Java and Pipeline: Groovy Libraries/Groovy/Script Security versions.
3. Record consumer job, Jenkinsfile path, source SHA, build cause and requested library version.
4. Prove the library retriever, repository, ref/tag and resolved commit.
5. Inspect sandbox/Script Security and CPS stack messages before changing approvals or trust.
6. Confirm agent/label/workspace only if failure occurs after agent allocation.
7. Inspect credential/external systems only if the library actually reached those steps.
8. Apply the smallest correction, publish a new library revision, and rerun only the affected disposable consumer.

2. Intentionally broken example: mutable default version

Start with a consumer that requests only @Library('academy-lib') _ while the Jenkins library configuration points default version at mutable main. Build #41 succeeds. A library maintainer changes main to rename a required argument. Build #42 of the same application SHA now fails.

Build #41  consumer=8c4...  library main -> 1a2...  SUCCESS
Build #42  consumer=8c4...  library main -> 7f9...  FAILURE
java.lang.IllegalArgumentException: required parameter 'component' missing

Interpretation: consumer source did not change; library source did. Preserve both builds and library SHAs. Least-destructive repair: publish/reselect a known-good version or a compatibility release, then update consumers deliberately. Do not delete #42, retry until green or move main backward without release evidence.

3. Trusted library as controller privilege

A trusted library can access Jenkins internals and unsafe APIs. Failure mode: an ordinary application team gains write access to that library repository and can modify a helper called by many jobs. That is not merely “code reuse”; it is a controller-compromise path.

Repair the governance boundary: restrict repository write/merge rights, require review/signing/branch protection as appropriate, separate trusted privileged code from ordinary sandboxed helpers, and audit historical library commits used by sensitive builds.

4. Sandbox/Script Security failures

When an untrusted library hits a rejected signature, preserve the rejection text and identify the exact API. Do not reflexively approve it. Ask whether the operation can use an existing safe Pipeline step, move to an agent-side tool, or requires a narrowly reviewed trusted library. Approval is a security mutation and needs the same evidence discipline as a credential permission change.

5. CPS and serialization pitfalls still apply

Shared Library Groovy is subject to the same CPS model from Chapter 13. A library can retain a non-serializable object across sleep/input/sh, misuse @NonCPS, or invoke Pipeline steps from a context that cannot suspend. Diagnose the stack trace and library commit first; moving the code into a library does not make CPS rules disappear.

6. Hidden side effects and privilege escalation

Failure mode: qualityGate() quietly publishes to an external repository using a globally available credential. The consumer appears to request “quality” but actually mutates an external system. Repair by splitting read-only verification from explicit publication/deployment APIs, binding credentials only in the reviewed privileged path, and naming side effects in the public contract.

7. Controller resource pressure

Large libraries, huge global variable scripts, controller-side data processing and many dynamically loaded classes can increase Pipeline compilation time, heap use and CPS persistence overhead. Measure build startup/compilation time, controller CPU/heap and library size before adding executors or agents—the bottleneck may be controller orchestration, not capacity.

8. Causal failure map

9. Actions that require explicit caution

Changing trusted-library SCM rights, Script Approvals, global library trust, credentials, plugin versions or controller restart state can widen privilege or affect many jobs. Use only disposable lab values here. Never disable Script Security, expose secrets, run untrusted builds on the controller, or grant broad admin credentials to make a library test pass.

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.