Checkpoint Lab — Groovy CPS, Serialization, @NonCPS, Pipeline State, Restarts, and Common Pipeline Programming Pitfalls

1. Checkpoint mission

You will use one synthetic SCM-backed Pipeline job to demonstrate three common CPS programming pitfalls, preserve each broken build as evidence, repair the code in new revisions, then pause a final safe build, restart the disposable controller, and prove that the same Pipeline run resumes.

2. Record the baseline before any run

• Jenkins core: expected lab baseline 2.568.3 LTS.
• Java: record actual controller Java (21 or 25 supported by this LTS).
• Pipeline: Groovy, Pipeline: Supporting APIs, Script Security versions.
• Job full name, SCM URL, initial source SHA, sandbox enabled.
• Agent label lab-linux, executor count, and workspace root.
• Pipeline durability setting in effect for the job.
• Disposable controller name jenkins-ch13-controller and persistent JENKINS_HOME mount.

git init jenkins-ch13-checkpoint
cd jenkins-ch13-checkpoint
git config user.name "Jenkins Chapter 13 Checkpoint"
git config user.email "jenkins-ch13-checkpoint@example.invalid"
printf 'chapter13-checkpoint\n' > README.txt
git add README.txt && git commit -m 'ch13 checkpoint baseline'
git rev-parse HEAD

3. Predictions required before execution

Write predictions.md before running anything:

1. When a Matcher remains reachable across sleep, predict that the build may fail while persisting CPS state; the external synthetic target remains unchanged.
2. When a Pipeline is paused at input and the controller restarts cleanly, predict that the same build number/URL and Pipeline continuation return.
3. Predict that a plain workspace scratch file is agent/workspace state and is not equivalent to persisted CPS program state.
4. Predict that the synthetic external marker, stored outside the cleaned workspace for this lab, remains independent of Pipeline continuation state.

4. Pitfall 1 — non-serializable object across suspension

node('lab-linux') {
  checkout scm
  def matcher = ('candidate build-77' =~ /build-(\d+)/)
  assert matcher.find()
  echo "candidate=${matcher.group(1)}"
  sleep 3
  echo "candidate_after=${matcher.group(1)}"
}

Run and preserve the complete failure. Repair in a new commit:

@NonCPS
String candidateId(String text) {
  def m = text =~ /build-(\d+)/
  return m.find() ? m.group(1) : 'none'
}

def candidate = candidateId('candidate build-77')
sleep 3
echo "candidate=${candidate}"

Expected repair evidence: a new source SHA, new build URL, no serialization exception, and value 77 after suspension.

5. Pitfall 2 — Pipeline step from @NonCPS

@NonCPS
def brokenAgentWork() {
  node('lab-linux') {
    echo 'should-not-be-called-from-NonCPS'
  }
}

brokenAgentWork()

Preserve the mismatch/anomalous behavior. Repair by making the native helper pure and moving Jenkins steps back into CPS code:

@NonCPS
String normalizeLabel(String value) {
  return value.trim().toLowerCase()
}

def label = normalizeLabel(' LAB-LINUX ')
node(label) {
  echo "allocated=${env.NODE_NAME}"
}

6. Pitfall 3 — CPS closure passed to native toSorted

def ordered = ['bbb', 'a', 'cccc', 'dd'].toSorted { left, right ->
  left.length() <=> right.length()
}
echo "ordered=${ordered}"

Record any CPS mismatch warning or incorrect result. Repair by moving the complete native sort into @NonCPS:

@NonCPS
List<String> sortNames(List<String> names) {
  return names.toSorted { left, right -> left.length() <=> right.length() }
}

def ordered = sortNames(['bbb', 'a', 'cccc', 'dd'])
echo "ordered=${ordered}"

The returned list contains strings and is safe durable state.

7. Final repaired Jenkinsfile with restart checkpoint

@NonCPS
String candidateId(String text) {
  def m = text =~ /build-(\d+)/
  return m.find() ? m.group(1) : 'none'
}

@NonCPS
List<String> sortNames(List<String> names) {
  return names.toSorted { a, b -> a.length() <=> b.length() }
}

def state = [candidate: candidateId('candidate build-77'), names: sortNames(['bbb','a','cccc','dd'])]
echo "before_restart job=${env.JOB_NAME} build=${env.BUILD_NUMBER} state=${state}"

timeout(time: 15, unit: 'MINUTES') {
  input message: 'Restart the disposable controller now, then return and continue', ok: 'Continue'
}

echo "after_restart job=${env.JOB_NAME} build=${env.BUILD_NUMBER} state=${state}"

node('lab-linux') {
  checkout scm
  sh '''
    set -eu
    mkdir -p evidence
    git rev-parse HEAD > evidence/source-sha.txt
    printf 'job=%s\nbuild=%s\nnode=%s\nworkspace=%s\n' \
      "$JOB_NAME" "$BUILD_NUMBER" "$NODE_NAME" "$WORKSPACE" > evidence/run.txt
  '''
  writeFile file: 'evidence/cps-state.txt', text: "${state}\n"
  archiveArtifacts artifacts: 'evidence/*', fingerprint: true
}

8. Restart drill

1. Start the final repaired build and wait until it pauses at input.
2. Record build URL/number, source SHA, and current stage/step.
3. On the disposable controller host, verify the exact container name.
4. Run docker restart jenkins-ch13-controller.
5. After Jenkins returns, reopen the same build URL and verify the input step is still associated with that same run.
6. Approve and let the build complete.
7. Compare before_restart and after_restart: job, build number, and the compact state map must match.

9. Prove external state is independent

Create a synthetic marker outside the cleaned agent workspace before the restart, for example in a dedicated lab volume or host-mounted directory:

mkdir -p /tmp/jenkins-ch13-external
printf 'operation=checkpoint-001\n' > /tmp/jenkins-ch13-external/checkpoint-001.done
sha256sum /tmp/jenkins-ch13-external/checkpoint-001.done

After Jenkins resumes, verify the same marker and digest independently. The marker did not survive because of CPS—it survived because it is external state. This distinction is the point of the exercise.

10. Required evidence packet

• baseline.txt: Jenkins/Java/Pipeline plugin versions and durability assumption.
• predictions.md.
• Broken build URLs/numbers/source SHAs for all three pitfalls.
• Exact first-failure exception or CPS mismatch warning for each pitfall.
• Repaired source SHAs and successful build URLs.
• Read-only program.dat path/size/timestamp metadata for one paused run, if available.
• Restart-before and restart-after console lines proving the same build identity/state.
• Agent/node/workspace/source evidence artifact.
• External marker path/digest and explanation that it is not CPS state.
• limitations.md: timing of serialization errors can vary; internal run files are not a supported repair API.

11. Verification checklist

12. Cleanup and rollback

Download the evidence packet, then remove only the synthetic Chapter 13 repository, job, lab-only external marker directory, and disposable controller resources created for this checkpoint. Do not remove shared Pipeline or Script Security plugins, shared agents, credentials, or unrelated jobs.

13. What Chapter 13 adds to the operating model

You can now explain why a Pipeline can survive a controller restart, why some ordinary Groovy patterns do not survive CPS transformation, how to keep native helpers inside a safe @NonCPS boundary, and how to prevent controller resources from becoming the hidden bottleneck.

Chapter 14 builds on that state model by separating workspace files from durable evidence using stash/unstash, archiveArtifacts, fingerprints, test reports, coverage, and explicit build-evidence retention.

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.