Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 40 ยท Pipeline as Code

Scripted Pipeline and Groovy for Jenkins

Learn scripted Jenkins pipelines: node blocks, try/catch/finally, Groovy basics, closures, CPS limits, @NonCPS, the sandbox and script approval, and when to use script.

Declarative Pipeline is a fixed outline you fill in. Scripted Pipeline is the original style: an ordinary Groovy program that calls Jenkins steps. There is no required shape. You write node { ... }, call stage, loop, catch exceptions and decide everything yourself. That freedom is powerful and easy to abuse, so it helps to know exactly what you are getting.

Even if you write declarative pipelines, you will meet Groovy constantly: inside script { } blocks, in expression { } conditions and in shared libraries. The real thing needs a Jenkins server, so Groovy and pipeline code appear in read-only blocks. The runnable examples are stand-ins in JavaScript: a comparison of the two styles and a tiny interpreter for a small scripted-pipeline subset.

Declarative vs scripted

Declarative Fixed sections, checked before it runs.
Scripted Plain Groovy, checked as it runs.

Both run on the same engine and can be mixed with script blocks.

1 / 2

A scripted pipeline

GROOVY
node('linux') {
  stage('Checkout') {
    checkout scm
  }
  stage('Build') {
    sh 'make build'
  }
  stage('Test') {
    try {
      sh 'make test'
    } catch (e) {
      currentBuild.result = 'UNSTABLE'
      echo "Tests failed: ${e.message}"
    } finally {
      junit 'reports/*.xml'
    }
  }
}

The pieces:

  • node('linux') { ... } asks for an executor on an agent with that label, creates a workspace, and runs the block there. Without node, a sh step has nowhere to run (only the controller's lightweight executor, which should never run builds). The label is optional: node { ... } uses any agent.
  • stage('Name') { ... } only labels a part of the run so that it shows in the stage view. Unlike declarative stages it does not skip, retry or decide anything.
  • try / catch / finally is ordinary Groovy exception handling. A failing step throws, and you decide what to do. In declarative you would reach for post or catchError.
  • parallel takes a map of closures:
GROOVY
parallel(
  'unit': { node { sh 'make unit' } },
  'lint': { node { sh 'make lint' } },
  failFast: true
)

The whole file is a script: no pipeline { } wrapper, no required agent, and no up-front validation of structure. A typo in a rarely used branch only shows up when that branch runs.

Groovy basics you need

Groovy looks like Java with less ceremony. For pipelines, this much goes a long way:

GROOVY
def name = 'shop'                       // dynamic typing with def
def version = "1.${env.BUILD_NUMBER}"   // double quotes interpolate (a GString)
def targets = ['dev', 'staging']        // a list
def sizes = [small: 1, large: 4]        // a map

targets.each { t -> echo "Deploy to ${t}" }   // a closure with a named parameter
sizes.each { key, value -> echo "${key}=${value}" }

if (env.BRANCH_NAME == 'main' && targets) {
  echo 'main branch with targets'         // empty lists and null are falsy
}

def greet(String who = 'world') {         // a method with a default value
  return "Hello, ${who}"
}
echo greet()

Three habits save time:

  1. Quotes matter. 'single' is a plain string; "double" interpolates ${...}. Never put secrets in double-quoted sh strings (see Credentials and Secrets).
  2. Closures ({ x -> ... }) are blocks of code passed around. The implicit parameter is called it when you do not name one.
  3. Truthiness is generous: null, 0, empty strings, empty lists and empty maps are false. That is convenient, and the source of the string 'false' being true (see Environment Variables and Parameters).

CPS: why pipeline Groovy is special

Jenkins can restart while a pipeline is running, and the build carries on afterwards. To make that possible, the Pipeline engine does not run your Groovy directly. It transforms the code into continuation-passing style (CPS) so it can save the exact position and local variables to disk, and resume later.

That has three consequences:

  • Variables must be serializable. If you keep an object that cannot be saved (a regex Matcher, an iterator, a parsed JSON object from some libraries) in a local variable across a step, the build fails with java.io.NotSerializableException. Convert to plain strings, lists and maps early, and keep such objects inside a single method.
  • Some Groovy library methods behave oddly or are unsupported when they take closures, particularly sorting and collection helpers on certain types. If a pure-Groovy snippet misbehaves only in a pipeline, CPS is the first suspect.
  • Heavy computation is slow. Loops over thousands of items in CPS code can be much slower than the same loop in plain Groovy.

@NonCPS

Annotate a method with @NonCPS to run it as ordinary Groovy, bypassing the transformation:

GROOVY
@NonCPS
def parseVersions(String text) {
  def result = []
  def matcher = text =~ /v(\d+)\.(\d+)/
  while (matcher.find()) {
    result << matcher.group(1) + '.' + matcher.group(2)
  }
  return result            // return plain data, not the Matcher
}

The rules: a @NonCPS method must not call pipeline steps (sh, echo, node, anything that Jenkins pauses on), because the engine cannot save its state mid-call. Use it for pure data crunching, return simple types, and keep it small.

The Groovy sandbox and script approval

Letting a pipeline author run arbitrary Groovy on the controller would hand them the whole server. So pipelines loaded from a repository run in the Groovy sandbox, which allows only a whitelist of safe methods. If your code calls something that is not whitelisted, the build fails with an error like:

TEXT
org.jenkinsci.plugins.scriptsecurity.sandbox.RejectedAccessException:
Scripts not permitted to use new java.io.File java.lang.String

(The signature varies; the shape of the message is what matters: Scripts not permitted to use ... followed by the method.) An administrator can then review the request under Manage Jenkins, In-process Script Approval and approve or deny it. Approve only what you understand. A signature such as staticMethod java.lang.System exit int or anything touching Runtime, files or the Jenkins object itself should make you stop. The safer fix is usually to avoid the method, use a built-in step instead (readFile, writeFile, readJSON from the Pipeline Utility Steps plugin), or move the code into a trusted shared library that administrators control. More on this in Security, Users and Authorization.

Declarative or scripted?

For new work, start declarative. It validates before running, reads the same everywhere, and gives you post, when, options and the stage view for free. Drop into script { } only for the few lines that need loops, variables or conditions the directives cannot express.

Scripted fits when a pipeline is genuinely dynamic: the list of stages comes from data, you need complex error handling, or the logic is shared. Even then, most teams put that logic in a shared library and keep the Jenkinsfile short. If you can read both styles, you can work on any Jenkinsfile you inherit.

Model: declarative and scripted compared

The first stand-in shows the practical difference. The "declarative" version is data that a checker validates before anything runs. The "scripted" version is a function, so a mistake appears only when execution reaches it.

JS Checked first vs found when it runs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The declarative version never started, and the scripted one built, then failed at its second stage. That timing difference is the main reason declarative is the default recommendation.

Model: a tiny scripted-pipeline interpreter

The second stand-in is a mini-interpreter for a very small subset of scripted syntax: node, stage, def, echo, error and try / catch / finally, with double-quoted ${...} interpolation. It is not Groovy, and it handles nothing beyond that subset, but writing it shows what the real engine does: parse blocks, run them in order, and make finally run whatever happens.

JS A mini scripted-pipeline interpreter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output against the source. error throws, the line after it is skipped, catch receives an object with a message, finally runs, and the pipeline then continues with the Done stage because the exception was handled. That is exactly what Groovy does in a real scripted pipeline, with a real engine, real steps and full Groovy in place of this small subset.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the node block do in a scripted pipeline?

    node requests an executor (optionally by label) and a workspace; steps like sh need that context.
  2. 2. Why does Jenkins transform pipeline Groovy to CPS?

    CPS lets the engine save and resume the exact position and variables, at the cost of some Groovy limitations.
  3. 3. Which rule applies to a @NonCPS method?

    The engine cannot save state while a NonCPS method runs, so steps are forbidden. Use it for pure data work.
  4. 4. A build fails with 'Scripts not permitted to use method ...'. What is the right first reaction?

    The sandbox exists to protect the controller. Review the signature before approving anything.
  5. 5. When is declarative the better default?

    Declarative catches structural mistakes early and covers most needs; use script blocks for small dynamic parts.

Summary

  • Scripted Pipeline is a Groovy program built around node, stage, try/catch/finally and parallel; declarative is a validated outline.
  • Groovy basics: def, GString interpolation with double quotes, lists, maps, closures and generous truthiness.
  • CPS makes builds restart-safe but limits serialization and some library calls; @NonCPS is the escape hatch for pure, step-free methods.
  • The sandbox whitelists methods; approve script requests carefully, or prefer built-in steps and trusted shared libraries.
  • Default to declarative and use script { } for the few places that need real code.

Next, move on to getting your code into Jenkins in Checking Out Code with Git.