How pipeline Groovy really runs: CPS, serialization and the sandbox
Continuation-passing style
Jenkins doesn't run your Jenkinsfile as normal Groovy. It transforms it into CPS (continuation-passing style) so the pipeline can pause and resume: waiting hours on input, sleeping, surviving a controller restart. At each step the pipeline's state — local variables, the call stack — is serialized to disk (program.dat in the build directory).
Consequences:
- All Groovy runs on the controller, interpreted slowly. Loops over thousands of items, parsing big files in Groovy, or complex string processing burn controller CPU. Push heavy work into
shwith proper tools (jq,yq, Python). - Everything held across a step must be serializable. Objects like
java.util.regex.Matcher, iterators, some JSON objects, or an HTTP connection aren't. Holding one while calling a step (sh,echo,sleep) causesjava.io.NotSerializableException. - Some Groovy features misbehave under CPS — notably closures passed to certain JDK/Groovy methods (e.g.
sort { }with a comparator closure,toSorted, someeachusages historically). Results can be silently wrong. Classicforloops are always safe.
@NonCPS
Mark a method @NonCPS to run it as normal Groovy — fast, no checkpoints, unrestricted closures:
@NonCPS
def parseVersion(String text) {
def m = (text =~ /version=(\d+\.\d+\.\d+)/)
return m ? m[0][1] : null // Matcher never crosses a step boundary
}
Rules: a @NonCPS method must not call pipeline steps (sh, echo, readFile...) — they rely on CPS — and should take and return simple serializable values. Use it for pure computation: parsing, sorting, transforming data.
The Groovy sandbox and script approval
Pipelines from SCM and untrusted libraries run in the Groovy sandbox, which allows only whitelisted method calls. Calling something else fails with:
org.jenkinsci.plugins.scriptsecurity.sandbox.RejectedAccessException:
Scripts not permitted to use method java.lang.String execute
An admin can approve the signature under Manage Jenkins → In-process Script Approval. Be careful: some approvals (e.g. Runtime.exec, getClass, reflection, Jenkins.instance) let any pipeline author run arbitrary code on the controller and read every credential. Prefer a pipeline step or plugin that does the job, or move logic into a trusted library reviewed by the platform team.
Trusted vs untrusted libraries
- Global shared libraries configured by admins are trusted: they run outside the sandbox with full access. Anyone who can push to that library's repo effectively has controller-level access — protect it with branch protection, required reviews and CI.
- Folder-level libraries are untrusted: sandboxed like Jenkinsfiles.
Performance guidance
- Keep pipelines thin: orchestrate tools, don't compute in Groovy.
- Avoid huge
echooutputs and giant log lines. durabilityHint('PERFORMANCE_OPTIMIZED')reduces checkpoint writes for pipelines that don't need to resume after a crash.- Don't make HTTP calls with raw Java classes; use
httpRequest(HTTP Request plugin) orcurlinsh.