Opscraft
Groovy for pipelines · Lesson 5 of 8 · 5 min read

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).

Enlarge diagramsh 'build'checkpointinput'Deploy?'checkpointsh 'deploy'Everything held across a step is serialised to disk, so it must be serialisable.A regex Matcher or an iterator kept across sh → NotSerializableException.
Figure 1. CPS: Jenkins saves the pipeline's state at every step, so it can pause for days on input or survive a controller restart.
Swipe sideways to see all of it, or tap to open it full screen.

Consequences:

  1. 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 sh with proper tools (jq, yq, Python).
  2. 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) causes java.io.NotSerializableException.
  3. Some Groovy features misbehave under CPS — notably closures passed to certain JDK/Groovy methods (e.g. sort { } with a comparator closure, toSorted, some each usages historically). Results can be silently wrong. Classic for loops 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.

Enlarge diagramNormal pipeline code (CPS)@NonCPS methodCan call steps: sh, echo, readFileSlow, checkpointedValues must be serialisablePlain fast GroovyMust NOT call pipeline stepsSimple values in and out (parse, sort)
Figure 2. When to reach for @NonCPS.
Swipe sideways to see all of it, or tap to open it full screen.

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.

Enlarge diagramJenkinsfilecalls a methodsandboxon the allow-list?runsapproved signatureRejectedAccessadmin may approvenarrowlyyesno
Figure 3. The Groovy sandbox: untrusted pipeline code may only call approved methods. Anything else waits for an admin.
Swipe sideways to see all of it, or tap to open it full screen.

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.
Enlarge diagramGlobal library (trusted)Folder library (untrusted)Configured by adminsNo sandbox: full controller accessProtect with required reviewsConfigured per folderSandboxed like a JenkinsfileSafer for team-owned code
Figure 4. Trusted libraries run outside the sandbox. Whoever can merge into them effectively controls the Jenkins controller.
Swipe sideways to see all of it, or tap to open it full screen.

Performance guidance

  • Keep pipelines thin: orchestrate tools, don't compute in Groovy.
  • Avoid huge echo outputs 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) or curl in sh.