Scripted Pipeline, Groovy Control Flow, node Blocks, Dynamic Logic, and When to Use Scripted Pipelines: Configuration, Design Choices, and Tradeoffs

1. The first design decision: do you need Scripted at all?

Scripted Pipeline is most valuable when the orchestration graph genuinely depends on validated runtime data. It is not automatically “more advanced.” A static workflow written in Scripted form can be harder to review because the reader must infer structure from general Groovy control flow rather than from Declarative grammar.

2. Pipeline step versus ordinary Groovy method

A Pipeline step participates in Jenkins execution semantics: it may schedule work, suspend, persist state, interact with credentials, or create build evidence. An ordinary Groovy method merely computes. That distinction matters more than the syntax.

def normalizedTargets(String raw) {
  raw.split(',')
     .collect { it.trim() }
     .findAll { it }
     .unique()
}

def targets = normalizedTargets('lint, unit, lint')
echo "targets=${targets.join(',')}"

This helper returns serializable strings/lists. It is small and deterministic. It does not call node, echo, sh, or other Pipeline steps.

3. When @NonCPS is appropriate—and when it is not

@NonCPS skips CPS transformation for a method. It can help with certain pure Groovy/library operations that do not behave correctly under CPS, but the method cannot call CPS-transformed Pipeline steps. Inputs and outputs should be simple serializable values.

@NonCPS
def compactLabels(List labels) {
  labels.collect { it.toString().trim() }.findAll { it }.unique().sort()
}

def labels = compactLabels(['linux', 'linux', 'x86_64'])
echo "labels=${labels.join(',')}"

4. One large node block versus targeted allocations

Node boundaries are infrastructure boundaries. Design them from executor capacity, workspace dependency, toolchain, network, and credential trust—not from indentation preference.

5. Dynamic stages versus static readability

A dynamic stage for each validated component can make a heterogeneous build easy to visualize. It can also produce unstable dashboards, unbounded stage counts, difficult trend comparison, and controller overhead when the list is large. Cap cardinality and normalize names.

def components = ['api', 'worker', 'web']
if (components.size() > 10) {
  error "component count ${components.size()} exceeds lab limit"
}
components.each { component ->
  stage("Test ${component}") {
    node('lab-linux') {
      sh "./test-component '${component}'"
    }
  }
}

In production, validate component before shell use and consider whether parallelism belongs here. Chapter 21 treats parallel and matrix capacity in depth.

6. Sandbox versus unsandboxed execution

Sandboxed Pipeline limits direct access to Jenkins/controller APIs. Approving an unsafe signature expands what Pipeline authors can do on the controller. That is a governance decision with security impact, not a routine development step. Trusted Shared Libraries can also execute privileged logic depending on configuration, so moving code into a library does not erase the trust question.

7. Restartability changes design choices

A Scripted Pipeline can survive supported controller restarts because Pipeline program state is persisted around asynchronous operations. Restartability does not mean every object is serializable or every external side effect is repeat-safe. Record side-effect identifiers before a suspension/restart and design idempotency explicitly.

For example, creating an external release and then sleeping is risky if a later rerun cannot tell whether the release already exists. Persist the release ID as build evidence and make the external operation create-or-update or otherwise reconcile safely.

8. Worked scenario: twelve components, two trust zones

A repository contains a validated manifest of 12 components. Ten require ordinary tests; two require signing on a restricted agent.

1. Parse/validate the manifest into simple serializable component records.
2. Reject more than the documented maximum cardinality.
3. Use ordinary lab-linux agents for tests.
4. Archive immutable package digests.
5. Move only approved digests to a restricted signing stage/agent.
6. Bind signing credentials only inside the restricted node/stage.
7. Record component, source SHA, unsigned/signed digest, node identity, and signing result.

Scripted Pipeline is defensible here if the manifest truly varies and the dynamic stages improve evidence. If the 12 stages are stable, Declarative may still be simpler.

9. Decision table

10. Mini ADR exercise

Write a short architecture decision record with: requirement, why Declarative is insufficient or sufficient, source of dynamic data, maximum cardinality, node labels/trust zones, credential boundaries, serializable state model, sandbox assumptions, restart/side-effect strategy, plugin versions, rollback path, and observable evidence. If you cannot justify those points, the Scripted design is probably not mature enough.

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.