Trusted Libraries and Versioned APIs

Scenario: A mutable trusted library changes all production builds without application commits.

Pipeline example

@Library('delivery-lib@v3') _
companyDeploy artifact: env.DIGEST, environment: 'staging'

Trust extends controller authority

A globally trusted library may call Jenkins and JVM APIs outside the Groovy sandbox. Anyone able to modify its referenced branch can effectively gain controller authority, regardless of ordinary folder permissions. Protect the repository, require review and immutable tags, isolate maintainers, and audit configuration. Folder-scoped or untrusted libraries remain sandboxed and suit team convenience code.

Pinning a version is reproducible only if the SCM reference is immutable. A moving v3 branch distributes fixes centrally but changes consumer behavior without application commits. Use immutable release tags for releases, curated moving channels for managed adoption, and explicit revocation when vulnerable versions must be blocked.

Evolve the contract as a product

Document arguments, defaults, validation, result behavior, credentials, side effects, and return values. Add compatible features within a major line and publish migrations for breaking changes. Test against supported Jenkins core and plugin baselines because library steps depend on plugin APIs and running Pipelines may resume after upgrades.

Canary a new revision across representative consumers. Log the resolved library SHA. Keep the previous known-good immutable version ready and maintain a consumer inventory so a faulty central release can be contained without guessing which repositories imported it.

Goal: Practice the concrete behavior in jenkins-declarative-rescue. Learn sections have no Jenkins terminal; the Jenkins lab opens the real shared service in a new full-screen tab inside your private folder.