Shared Libraries, Global Variables, vars, src, resources, Versioning, Testing, and Pipeline Product Design: Configuration, Design Choices, and Tradeoffs

1. Global trusted versus folder/untrusted

Trust and scope solve different problems. A library can be untrusted but still too broadly available, or narrowly scoped but dangerously trusted.

2. Implicit versus explicit loading

Implicit loading reduces Jenkinsfile boilerplate but hides a dependency and default version. Explicit @Library makes the dependency visible during script compilation and works well for stable static imports. The dynamic library step can choose a version at runtime but cannot retroactively change classes already resolved during compilation.

For a production platform, prefer explicit dependencies unless there is a strong reason to make a library part of the platform’s implicit runtime contract.

3. Branch, tag or commit?

A common operating model uses protected semantic-version tags and records the resolved commit SHA in evidence.

4. Thin wrapper versus large framework

A thin library gives names to repeated primitives—publishing test evidence, standardizing artifact metadata, validating parameters—while leaving stages and privilege decisions visible. A large framework can make onboarding concise but can also hide side effects, multiply CPS state, slow compilation and make incidents harder to reason about.

Jenkins Pipeline best practices explicitly warn against overriding built-in steps and against large global variable declaration files. If your library redefines sh, timeout or other core semantics, users can no longer rely on Jenkins documentation to understand their Pipeline.

5. Semantic versioning versus rolling main

SemVer is useful when the library has a real public contract: patch = compatible fix, minor = compatible feature, major = intentional break. Rolling main may be acceptable for experimental teams if every consumer is tested together and rollback is controlled, but it is a poor default for independently released services.

Versioning must include resources, dependency changes and trust-policy assumptions—not only Groovy function signatures.

6. Third-party dependencies and classpath boundaries

Adding libraries through @Grab or other dynamic dependency mechanisms expands supply-chain and controller classpath risk. Prefer Jenkins-provided Pipeline steps or small, reviewed dependencies with pinned versions and known provenance. If a task is naturally an external build tool operation, run it on an agent rather than turning the Shared Library into a controller-side application framework.

7. Worked decision scenario

Suppose 40 services need a standard “publish JUnit + archive metadata” helper. They do not need Jenkins internals. Teams release independently and need one-month migration windows.

8. Rollout and rollback contract

A library release should define: supported Jenkins/plugin baseline, supported consumer API versions, deprecations, rollout cohorts, owner, rollback version and evidence that proves which consumers moved. Do not “fix forward” a controller-wide library failure by editing the same mutable branch while builds are running.

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.