Groovy CPS, Serialization, @NonCPS, Pipeline State, Restarts, and Common Pipeline Programming Pitfalls: Configuration, Design Choices, and Tradeoffs

1. Design for the execution model you actually have

The easiest CPS problems to fix are the ones you avoid by design. A Pipeline should carry identifiers and small decisions—not live service clients, parser iterators, giant object graphs, or mutable handles. Prefer durable values such as strings, numbers, booleans, and compact maps/lists. Convert native library results into that durable shape before the next suspension.

2. CPS-safe data versus complex objects

3. Pipeline step versus Java/Groovy library call

Use a Pipeline step when Jenkins must orchestrate Jenkins-aware behavior: allocate a node, run an agent process, wait, archive evidence, request input, or interact through a plugin contract. Use an ordinary library call for tiny deterministic calculations that do not need Jenkins state. The mismatch risk appears when native code calls back into CPS-transformed closures or methods.

If a library API accepts a closure/comparator/callback, verify that the combination is supported by current Pipeline CPS semantics. Do not assume every Groovy idiom behaves like standalone Groovy.

4. @NonCPS helper versus external tool

5. Controller-side computation versus agent-side script

Even a native @NonCPS method still runs in the controller process. It may be faster than CPS-transformed Groovy, but it is not free. If the task is CPU-heavy, memory-heavy, or scales with repository size, offload it.

node('lab-linux') {
  sh './scripts/compute-summary.sh raw-results.json > summary.env'
  def summary = readProperties file: 'summary.env'
  echo "failed=${summary.failed} total=${summary.total}"
}

The controller retains only two small values; the large raw data remains a workspace/artifact concern.

6. Durability mode: performance versus survivability

Pipeline durability controls how frequently transient Pipeline state is persisted. Maximum survivability writes more often; performance-optimized modes reduce I/O and increase the risk that a dirty shutdown loses recent running-Pipeline state. This is an operational policy decision, especially important for critical deployments.

7. Worked scenario: summarize a large test report

Requirement: a 150 MB JSON report must produce passed, failed, and duration. The run must survive controller restart and preserve the raw report.

Evidence should include parser tool/version, source SHA, raw report artifact digest, summary file, and Pipeline build URL.

8. Sandbox and approval are part of architecture

Do not disable the Groovy sandbox to “make code work.” Unsandboxed Pipeline code can invoke powerful controller APIs and requires administrative approval. Prefer supported Pipeline steps and sandbox-safe code. If an organization intentionally approves a script, treat that approval like privileged code change: review source/revision, scope, owner, and rollback.

9. Decision checklist

• Can the value be represented as a small serializable primitive/list/map?
• Does the operation need a Pipeline step or Jenkins context?
• Does a native helper call back into CPS-transformed code?
• How much controller CPU/heap does the work consume?
• What happens if the controller restarts halfway through?
• What external state exists outside Jenkins durability?
• What evidence proves the chosen boundary behaved as predicted?

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current Jenkins LTS and tested Java configurations.
• Pipeline CPS Method Mismatches — CPS transformation boundaries, @NonCPS, constructors, closures, and mismatch diagnostics.
• Pipeline: Groovy plugin — Pipeline execution engine, persistence model, program.dat, rehydration, and @NonCPS contract.
• Pipeline Best Practices — controller/agent boundaries, serializable state, and safe use of @NonCPS.
• Scaling Pipelines — durability modes, persistence trade-offs, controller CPU/memory, and restart implications.
• Script Security plugin — Groovy sandbox and script-approval security boundary.
• Jenkins Pipeline handbook — durable, pausable Pipeline fundamentals.