jenkins-groovy-scripting-best-practices

Jenkins Groovy Scripting Best Practices

Purpose

Jenkins Pipeline (both per-repo Jenkinsfiles and shared libraries) is written in Groovy, but it does not run like ordinary Groovy: it executes under the Groovy sandbox (a security boundary that blocks arbitrary Java/Groovy method calls unless explicitly approved) and under CPS (Continuation-Passing Style) transformation (so pipelines can pause/ resume across Jenkins restarts), both of which produce failure modes that look like bugs in your code but are actually artifacts of the execution model. This skill covers the sandbox/script-approval workflow, how to unit test shared library Groovy without a running Jenkins controller, and the specific Groovy/CPS pitfalls (closures capturing this, non-serializable state, @NonCPS usage) that recur in pipeline code.

When to use

• A pipeline or shared library fails with org.jenkinsci.plugins.scriptsecurity. sandbox.RejectedAccessException: Scripts not permitted to use ....
• Writing or reviewing Groovy code in a Jenkinsfile's script {} block or in a shared library's vars//src/ files (see jenkins-declarative-pipeline-per-repo and jenkins-centralized-shared-library for where this code lives).
• Setting up automated tests for shared library logic so changes are verified before a version tag is cut, rather than only discovered when a consumer's build breaks.
• Debugging NotSerializableException, unexpectedly re-executed code after a controller restart, or a closure that behaves differently than plain Groovy would suggest.
• Deciding whether a piece of logic should be @NonCPS-annotated.

Prerequisites & environment

• A Jenkins controller with the Script Security plugin (bundled with modern Jenkins Pipeline installs) — this is what enforces the sandbox and stores approved signatures under Manage Jenkins → In-process Script Approval.
• Administrator access to approve pending script signatures (only Jenkins admins can approve; a pipeline author who hits a RejectedAccessException must request approval, not self-approve unless they hold that role).
• For unit testing: a JVM project (Maven or Gradle) alongside the shared library repo, with the JenkinsPipelineUnit library (lesfurets:jenkins-pipeline-unit) added as a test dependency, and a test framework (JUnit 5 or Spock) to drive it.
• Groovy 2.x/3.x knowledge (whichever your Jenkins version bundles — check Manage Jenkins → System Information for the exact Groovy version) — syntax mostly matches plain Groovy but some newer Groovy language features may not be supported inside the CPS-transformed subset.