Checkpoint Lab — Shared Libraries, Global Variables, vars, src, resources, Versioning, Testing, and Pipeline Product Design

1. Scenario

The platform team owns ch24-platform-lib. Version 1 exposes releaseNote service:, version:. A proposed version 2 replaces service with component. You must prove the impact with one disposable consumer, preserve v1 support, and define a rollout that does not silently change other Pipelines.

2. Baseline assumptions

• Jenkins 2.568.3 LTS, Java 21.
• Pipeline: Groovy Libraries 805.va_fc79344957d; Pipeline: Groovy 4380.v6eb_8378b_9647; Script Security 1422.v06869826dd9b_.
• Git 5.10.1; Git Client 6.6.1.
• Local disposable Git repositories only; no production SCM credential.
• Library is untrusted/sandboxed for the lab; no privileged controller API is needed.
• One low-privilege agent; built-in node remains at zero executors.

3. Preflight and predictions

Record two predictions before execution: (1) the unchanged consumer succeeds against v1.0.0 and fails against intentionally incompatible v2.0.0; (2) switching back to v1.0.0 reproduces the original behavior because that tag/commit remains unchanged.

Also record controller/plugin versions, job full name, agent label, library repository URL, and verify that no credentials or Script Approvals are required.

4. Publish v1

// vars/releaseNote.groovy — v1
def call(Map cfg = [:]) {
    if (!cfg.service || !cfg.version) { error 'service and version are required' }
    writeFile file: 'evidence/release-note.txt',
              text: "service=${cfg.service}\nversion=${cfg.version}\napi=v1\n"
    echo "release-note ${cfg.service} ${cfg.version}"
}

Commit, test, tag v1.0.0, and record git rev-parse v1.0.0^{commit}. Configure the lab Shared Library through Modern SCM.

5. Consumer build A: v1

@Library('ch24-platform-lib@v1.0.0') _
pipeline {
  agent { label 'linux-lowtrust' }
  stages {
    stage('Contract') {
      steps { releaseNote service: 'payments', version: '3.4.5' }
    }
  }
  post { always { archiveArtifacts artifacts: 'evidence/**', allowEmptyArchive: true } }
}

Capture build URL/number/cause, consumer SHA, requested library tag, resolved library commit, agent/workspace and archived evidence.

6. Publish intentional breaking v2

// vars/releaseNote.groovy — intentionally breaking v2
def call(Map cfg = [:]) {
    if (!cfg.component || !cfg.version) { error 'component and version are required in v2' }
    writeFile file: 'evidence/release-note.txt',
              text: "component=${cfg.component}\nversion=${cfg.version}\napi=v2\n"
}

Test the new intended API, commit and tag v2.0.0. Change only the consumer library selector to v2.0.0; do not alter the old API call. Run Build B and preserve the expected failure. The evidence should point to the API incompatibility, not an agent or credential failure.

7. Prove rollback

Change the selector back to v1.0.0 and run Build C. Verify the resolved library commit exactly matches Build A and the archived release-note.txt again contains api=v1. This proves rollback by immutable library identity.

8. Publish a migration-compatible release

Create v2.1.0 that accepts component and, for a documented migration window, aliases old service with a deprecation message. Add tests for both call forms. The migration contract should specify the future major version in which service will be removed.

9. Required evidence packet

10. Cleanup and rollback

Delete only the disposable consumer job/folder and local lab repositories after preserving evidence. Remove the lab Shared Library configuration if it was created globally. Do not remove production libraries, approvals or credentials. If you tested trusted-library behavior in an isolated controller, revert only the explicit lab trust configuration.

11. What Chapter 24 adds to the production operating model

Shared Pipeline behavior is now governed like any other production dependency: explicit trust, protected source ownership, pinned/released identity, small public APIs, tests, compatibility promises, consumer provenance, staged migration and rollback. Chapter 25 moves to the next platform-wide dependency surface: the Jenkins plugin ecosystem, update-center dependencies, compatibility, pinning/removal and plugin governance.

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.