Checkpoint Lab — Scripted Pipeline, Groovy Control Flow, node Blocks, Dynamic Logic, and When to Use Scripted Pipelines

1. Checkpoint scenario

You own a synthetic repository whose trusted local manifest selects a subset of three allowed checks: lint, unit, and package. First implement a fixed Declarative Pipeline. Then implement a Scripted Pipeline that creates stages from the validated manifest. Inject a serialization error into the Scripted version, preserve the failure, repair it in a new commit, and prove the repaired evidence.

2. Baseline and preflight

3. Write predictions before execution

Create predictions.md with at least these predictions:

1. The fixed Declarative version will always display the same three stage names.
2. The Scripted version will create stages only for manifest entries that pass the allowlist and cardinality checks.
3. All sh commands will run inside node('lab-linux'); planning logic will not require an executor.
4. The intentionally retained regex Matcher across sleep will fail with serialization/CPS evidence before the final artifact stage.
5. The repaired revision will convert the temporary matcher result to a serializable String before suspension and archive evidence tied to the new SHA.

4. Create the synthetic repository

mkdir jenkins-ch11-checkpoint && cd jenkins-ch11-checkpoint
git init
git config user.name "Jenkins Chapter 11 Checkpoint"
git config user.email "jenkins-ch11-checkpoint@example.invalid"
cat > lab-task <<'EOF'
#!/usr/bin/env sh
set -eu
mkdir -p out
case "$1" in
  lint)    printf 'lint=ok\n' > out/lint.txt ;;
  unit)    printf 'unit=ok\n' > out/unit.txt ;;
  package) printf 'package=ok\n' > out/package.txt ;;
  *)       printf 'unsupported task\n' >&2; exit 2 ;;
esac
EOF
chmod +x lab-task
printf 'lint\nunit\npackage\n' > tasks.txt
git add .
git commit -m 'ch11: checkpoint project'
BASE_SHA=$(git rev-parse HEAD)
printf 'base_sha=%s\n' "$BASE_SHA"

5. Implement the fixed Declarative comparison

Save this as Jenkinsfile.declarative:

pipeline {
  agent { label 'lab-linux' }
  stages {
    stage('Checkout') {
      steps { checkout scm }
    }
    stage('Lint') {
      steps { sh './lab-task lint' }
    }
    stage('Unit') {
      steps { sh './lab-task unit' }
    }
    stage('Package') {
      steps { sh './lab-task package' }
    }
  }
  post {
    always {
      archiveArtifacts artifacts: 'out/*', allowEmptyArchive: true, fingerprint: true
    }
  }
}

This is clearer if all three tasks are always required. Run it as an SCM-backed Pipeline configured with Script Path Jenkinsfile.declarative. Record the source SHA, build number/URL, node/workspace, stages, and artifact digests.

6. Implement the dynamic Scripted version

Save this as Jenkinsfile:

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

def requested = []
readFile('tasks.txt').readLines().each { raw ->
  def taskName = raw.trim()
  if (taskName) {
    if (!allowed.contains(taskName)) {
      error "unsupported task: ${taskName}"
    }
    requested << taskName
  }
}
requested = requested.unique()
if (requested.size() > 3) {
  error "task count ${requested.size()} exceeds limit 3"
}

stage('Plan') {
  echo "selected=${requested.join(',')}"
}

node('lab-linux') {
  stage('Checkout') {
    checkout scm
    sh '''
      set -eu
      mkdir -p evidence
      {
        printf 'job=%s\n' "$JOB_NAME"
        printf 'build=%s\n' "$BUILD_NUMBER"
        printf 'build_url=%s\n' "$BUILD_URL"
        printf 'node=%s\n' "$NODE_NAME"
        printf 'workspace=%s\n' "$WORKSPACE"
        printf 'source_sha=%s\n' "$(git rev-parse HEAD)"
      } > evidence/context.txt
    '''
  }

  requested.each { taskName ->
    stage("Task: ${taskName}") {
      sh "./lab-task '${taskName}'"
    }
  }

  stage('Evidence') {
    sh 'sha256sum out/* > evidence/artifacts.sha256'
    archiveArtifacts artifacts: 'evidence/*,out/*', fingerprint: true
  }
}

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

def requested = []

node('lab-linux') {
  stage('Checkout') {
    checkout scm
  }

  stage('Plan') {
    readFile('tasks.txt').readLines().each { raw ->
      def taskName = raw.trim()
      if (taskName) {
        if (!allowed.contains(taskName)) {
          error "unsupported task: ${taskName}"
        }
        requested << taskName
      }
    }
    requested = requested.unique()
    if (requested.size() > 3) {
      error "task count ${requested.size()} exceeds limit 3"
    }
    echo "selected=${requested.join(',')}"
  }

  requested.each { taskName ->
    stage("Task: ${taskName}") {
      sh "./lab-task '${taskName}'"
    }
  }

  stage('Evidence') {
    sh '''
      set -eu
      mkdir -p evidence
      {
        printf 'job=%s\n' "$JOB_NAME"
        printf 'build=%s\n' "$BUILD_NUMBER"
        printf 'node=%s\n' "$NODE_NAME"
        printf 'workspace=%s\n' "$WORKSPACE"
        printf 'source_sha=%s\n' "$(git rev-parse HEAD)"
      } > evidence/context.txt
      sha256sum out/* > evidence/artifacts.sha256
    '''
    archiveArtifacts artifacts: 'evidence/*,out/*', fingerprint: true
  }
}

Run this good Scripted revision first and preserve its evidence. The dynamic value is visible: stage count follows the validated manifest, bounded to three allowed tasks.

7. Inject a serialization failure

In a new commit, add this between Plan and the task loop:

def releaseMatcher = ('release-42' =~ /release-(\d+)/)
sleep 2
echo "release=${releaseMatcher[0][1]}"

Commit it and record the broken SHA. Run the build. Preserve the first serialization/CPS stack trace, build URL, stage state, and proof that later evidence did not complete. Do not replay yet.

8. Repair the state model

Replace the retained matcher with a serializable string before the suspension:

def releaseId = ('release-42' =~ /release-(\d+)/)[0][1].toString()
sleep 2
echo "release=${releaseId}"

Commit the repair as a new revision. Run again. Verify that the build reaches all dynamic task stages and the Evidence stage.

9. Verify every prediction independently

10. Evidence packet

• baseline.txt: Jenkins core/Java and Pipeline: Groovy/Script Security/Nodes plugin versions.
• predictions.md.
• Job full names, build numbers/URLs, causes, and exact source/Jenkinsfile SHAs for Declarative, good Scripted, broken, and repaired runs.
• Queue/node/label/executor/workspace evidence.
• Dynamic selected-task list and stage names.
• Broken serialization stack trace.
• Archived evidence/context.txt, evidence/artifacts.sha256, out/*, and fingerprints.
• Statement that no real credential, sandbox approval, cloud service, or production target was used.
• limitations.md: dynamic cardinality capped at three; no parallelism; no external side effect.

11. Cleanup and rollback

Download the evidence packet. Delete only the Chapter 11 checkpoint jobs/repository branches created for the lab. Do not delete shared agents, controller plugins, or unrelated Pipeline jobs. If you changed any job configuration while comparing Script Paths, restore the documented intended path.

12. What Chapter 11 adds

You can now use Scripted Pipeline intentionally rather than reflexively: dynamic Groovy controls orchestration, node controls agent/workspace allocation, Pipeline steps preserve Jenkins semantics, substantial work remains on agents, CPS state stays serializable, and Script Security remains a deliberate trust boundary.

Chapter 12 builds on this by controlling failure itself: retry, timeout, catchError, input, waitUntil, aborts, and side-effect-safe resilience.

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.