Scripted Pipeline, Groovy Control Flow, node Blocks, Dynamic Logic, and When to Use Scripted Pipelines: Concepts, Architecture, and Mental Model

1. Why Scripted Pipeline exists

Chapter 10 used Declarative Pipeline to make common delivery structure explicit and validated. That structure is valuable, but some orchestration is genuinely dynamic: a validated list of components may be discovered at run time, different trusted inputs may require different node allocations, or a bounded loop may need to create a variable number of stages. Scripted Pipeline exposes more of Groovy's control-flow vocabulary for those cases.

The extra flexibility has a cost. A Scripted Jenkinsfile is not an ordinary Groovy program and it is not a shell script. Jenkins transforms most Pipeline Groovy into continuation-passing style (CPS) so it can save execution state around asynchronous Pipeline steps. That means you must reason about where code executes, what state must be serializable, when a node/workspace exists, and which APIs the Groovy sandbox permits.

2. Mental model: CPS program → decisions → node work → durable state

A Scripted Jenkinsfile is compiled into Pipeline program state on the controller. Groovy expressions make orchestration decisions. Pipeline steps can suspend and resume. A node step enters the queue, waits for an eligible executor, and creates a workspace on the selected agent. Inside that context, sh/bat start external processes on the agent. Jenkins persists enough Pipeline state to resume supported work after expected interruptions.

flowchart TD
 A[Jenkinsfile at exact SCM SHA] --> B[Groovy CPS program on controller]
 B --> C{Groovy control-flow decision}
 C --> D[Pipeline step]
 D --> E{node needed?}
 E -->|yes| F[Queue + label eligibility]
 F --> G[Executor + agent workspace]
 G --> H[sh/bat/tool process on agent]
 E -->|no| I[Controller-orchestrated Pipeline step]
 H --> J[Step result / files]
 I --> J
 J --> K[Persisted Pipeline run state]
 K --> L[Stage/build result + artifacts/evidence]

Do not interpret the diagram as “all Groovy is expensive controller work.” Most orchestration code is brief. The risk appears when large computations, huge in-memory objects, or controller APIs are used as if Jenkins were a general application server.

3. The smallest useful Scripted Pipeline

node('lab-linux') {
  stage('Observe') {
    echo "job=${env.JOB_NAME} build=${env.BUILD_NUMBER}"
    sh 'printf "node=%s\\nworkspace=%s\\n" "$NODE_NAME" "$WORKSPACE"'
  }
}

node('lab-linux') is a Pipeline step. It queues this body for an agent matching the label and gives the body a workspace. stage provides a named visualization/evidence boundary. echo is a Pipeline step. sh asks the agent to start a shell process. The shell receives environment variables such as NODE_NAME and WORKSPACE; Groovy does not become the shell.

4. Ordinary Groovy versus Pipeline steps

5. Bounded dynamic control flow

Scripted Pipeline can use familiar if/else, loops, maps, closures, and functions. The important word is bounded. The set of work should come from trusted or validated inputs, stage names should remain intelligible, and the resulting graph should not explode into hundreds of controller-managed branches accidentally.

def requested = ['lint', 'unit']
def allowed = ['lint', 'unit', 'package'] as Set

def selected = requested.findAll { allowed.contains(it) }

node('lab-linux') {
  selected.each { taskName ->
    stage("Check: ${taskName}") {
      sh "./lab-task '${taskName}'"
    }
  }
}

For an actual untrusted parameter, do not interpolate it into a shell command like this. Validate against an allowlist and pass it through a safer boundary. The example uses fixed synthetic values to focus on stage generation.

6. A node block is a scheduling and workspace decision

One large node block is easy to read but can hold an executor while controller-only decisions or waits occur. Several targeted node blocks can free capacity between phases and select different labels, but each allocation may use a different workspace or agent. If later phases require files, transfer them intentionally with artifacts/stashes or regenerate only when that behavior is explicitly safe.

7. CPS, suspension, and serializable state

Most Pipeline Groovy is CPS-transformed. When a Pipeline reaches an asynchronous step, Jenkins can persist the program state. Variables that remain reachable across such a suspension may need to be serializable. Keeping a non-serializable object such as a regex Matcher, an open stream, or many third-party objects across a sleep, input, node, or other suspension point can produce NotSerializableException or confusing CPS behavior.

// Good pattern: reduce temporary object to a serializable String before suspension.
def releaseText = 'release-42'
def releaseId = (releaseText =~ /release-(\d+)/)[0][1].toString()
sleep 1
echo "releaseId=${releaseId}"

@NonCPS is not a blanket performance or compatibility fix. A method marked @NonCPS must not call Pipeline steps such as echo, sh, node, or sleep. Prefer simple serializable data structures and external tools on agents for substantial computation.

8. Sandbox and script approval are trust controls

Pipeline scripts normally run in the Groovy Sandbox. When code attempts a method or API that is not approved, Script Security can reject the signature. That rejection is evidence of a trust boundary, not an instruction to approve everything. An unsandboxed/approved script may call powerful Jenkins controller APIs and therefore belongs to a much stronger administrative trust domain.

9. When Scripted is justified

10. Read-only inspection before editing

• Record Jenkins core/Java and Pipeline: Groovy, Script Security, and Nodes/Processes plugin versions.
• Record job full name, build number/URL, cause, and exact Jenkinsfile/source SHA.
• Inspect existing node labels and agent/workspace evidence.
• Identify every Groovy variable that may remain live across Pipeline steps.
• List any sandbox rejection or approved signature without approving anything new.
• Record stage names and build result so later dynamic changes can be compared.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS and tested Java configurations.
• Jenkins Pipeline handbook — Scripted Pipeline fundamentals, node, stages, and Jenkinsfile concepts.
• Pipeline Syntax — Scripted control-flow examples and Pipeline syntax reference.
• Pipeline Best Practices — controller-side Groovy, serialization, and Pipeline scalability guidance.
• Pipeline CPS Method Mismatches — CPS transformation, @NonCPS, serialization, and mismatch failure modes.
• In-process Script Approval — Groovy Sandbox and script/signature approval security model.
• Pipeline: Groovy — current CPS execution engine implementation and compatibility.
• Script Security — current sandbox/approval plugin baseline and security history.
• Pipeline: Nodes and Processes — node, workspace, and durable external-process support.