Checkpoint Lab — Pipeline Fundamentals, Jenkinsfile, Pipeline Engine, Durable Execution, Nodes, Workspaces, and Stages

1. Checkpoint scenario

You are validating whether a small Jenkins Pipeline is operationally understandable after a controller restart. The Pipeline must come from SCM, record immutable source/build/execution evidence, pause safely, survive a controlled restart, and archive a final packet. You must prove the same build resumed and explicitly state which state was controller-persisted versus agent/workspace-local.

2. Baseline assumptions to record

• Jenkins 2.568.3 LTS; controller and agent run on supported Java 21 or 25.
• Pipeline aggregator 608.v67378e9d3db_1.
• Declarative Pipeline 2.2293.v6e7193cec599.
• Pipeline: Groovy 4380.v6eb_8378b_9647.
• Pipeline: Job 1600.v6f36ed83529d.
• Pipeline: Nodes and Processes 1479.v56e587f413a_7.
• One disposable non-controller agent labeled lab-linux; controller built-in executors remain zero.
• A synthetic repository with no secrets/proprietary source.

If your installed versions differ, record the actual versions and verify compatibility rather than forcing the lab baseline.

3. Preflight and resource guards

Record controller identity, persistent JENKINS_HOME, controller port/binding, agent name/label, source repository URL, and the exact disposable controller restart command. Verify no production webhook, credential, deployment target, or shared controller is involved.

4. Create the source and capture immutable identity

Create a repository with payload.txt and the Jenkinsfile below. Commit both and record the resulting SHA as SOURCE_SHA_EXPECTED. The job should use Pipeline script from SCM.

git add Jenkinsfile payload.txt
git commit -m 'ch09: checkpoint pipeline'
SOURCE_SHA_EXPECTED=$(git rev-parse HEAD)
printf '%s\n' "$SOURCE_SHA_EXPECTED"

5. Checkpoint Jenkinsfile

pipeline {
  agent { label 'lab-linux' }
  options { timestamps() }
  stages {
    stage('Capture baseline') {
      steps {
        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)"
            printf 'java='; java -version 2>&1 | head -n 1
          } | tee evidence/before.txt
          sha256sum payload.txt > evidence/payload-before.sha256
        '''
      }
    }
    stage('Safe restart window') {
      steps {
        echo 'Restart only the verified disposable controller now.'
        sleep time: 4, unit: 'MINUTES'
      }
    }
    stage('Verify continuation') {
      steps {
        sh '''
          set -eu
          test -f evidence/before.txt
          {
            printf 'resumed_job=%s\n' "$JOB_NAME"
            printf 'resumed_build=%s\n' "$BUILD_NUMBER"
            printf 'resumed_node=%s\n' "$NODE_NAME"
            printf 'resumed_workspace=%s\n' "$WORKSPACE"
            printf 'source_sha=%s\n' "$(git rev-parse HEAD)"
          } | tee evidence/after.txt
          sha256sum payload.txt > evidence/payload-after.sha256
          diff -u evidence/payload-before.sha256 evidence/payload-after.sha256
        '''
      }
    }
    stage('Summarize') {
      steps {
        sh '''
          set -eu
          {
            echo 'controller_pipeline_state=resumed'
            echo 'workspace_state=observed-not-guaranteed'
            echo 'external_side_effects=none-in-this-lab'
          } | tee evidence/limitations.txt
        '''
      }
    }
  }
  post {
    always {
      archiveArtifacts artifacts: 'evidence/*', fingerprint: true
    }
  }
}

6. Write predictions before the run

Record at least these predictions in predictions.md before triggering the build:

1. The controller restart will not create a new build number; the original run will remain the identity being resumed.
2. The Pipeline will continue after the safe sleep step if controller state is persisted and resume is enabled.
3. The static lab agent/workspace will probably remain present, but Pipeline durability does not guarantee workspace survival in general.
4. Archived evidence will remain attached to the build after completion even if the workspace is later cleaned.

7. Execute and preserve the pre-restart state

Trigger the job manually. Record the queue item if observable, then the build URL/number and source SHA. Wait until Safe restart window is active. Save a screenshot/text note of the stage state and relevant console lines; do not edit the job or Jenkinsfile during the experiment.

8. Controlled restart

Use the exact restart method from preflight. For a disposable controller container, the conceptual operation is stop/start of that one container while preserving JENKINS_HOME. Do not remove the container volume, agent workspace, or job configuration.

After the controller reports healthy, return to the same build URL. Confirm the build number did not change and the run continues.

9. Independent verification

10. Optional controlled failure: remove workspace assumptions

After the successful checkpoint, copy the repository into a branch and redesign the Pipeline with agent none, using two different lab labels for Build and Verify. First predict that an untransferred workspace file will be absent on the second node. Run once to capture that failure. Then repair it with stash/unstash or deterministic recreation. This isolates dataflow design from controller durability.

11. Required evidence packet

• baseline.txt: Jenkins core/Java and installed Pipeline plugin versions.
• predictions.md: predictions written before execution.
• Job full name, build number/URL, trigger cause, source/Jenkinsfile SHA.
• Node/label/executor/workspace evidence and relevant tool versions.
• Stage/step state before restart and continuation observation after restart.
• Archived before.txt, after.txt, payload checksums, and limitations note.
• Any queue item/reason observed during the run.
• An explicit statement that no external deployment side effect was part of the mandatory lab.

12. Cleanup and rollback

Download the evidence packet first. Delete only the disposable Chapter 09 job/repository and chapter-specific controller/agent resources that you created. Do not delete shared plugins, global credentials, shared agents, or unrelated workspaces. If you changed a Pipeline durability setting for an optional experiment, restore the documented original setting after the experiment.

13. What Chapter 09 adds to a production operating model

You can now reason about Pipeline as persisted controller-orchestrated state rather than a shell script with a UI. You can separate run identity, CPS/program state, queue/node allocation, workspace/process state, retained artifacts, and external side effects—and you can prove restart behavior with evidence rather than assuming it.

Chapter 10 builds directly on this foundation by going deeper into Declarative Pipeline structure: agent, stages, steps, options, parameters, environment, tools, and post.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS line and tested Java configurations.
• Jenkins Pipeline handbook — Pipeline concepts, Jenkinsfile, development tools, shared libraries, and execution model.
• Getting Started with Pipelines — durability, pausing, and the reasons Pipeline differs from Freestyle automation.
• Pipeline Syntax — Declarative pipeline, agent, stages, steps, options, and restart-related directives.
• Scaling Pipelines — Pipeline durability modes, persistence tradeoffs, and restart implications.
• Pipeline plugin — the aggregator and current Pipeline plugin suite.
• Pipeline: Declarative — Declarative Pipeline implementation and compatibility.
• Pipeline: Groovy — CPS execution model and controller-side Groovy interpretation.
• Pipeline: Job — persisted Pipeline run/job implementation.
• Pipeline: Nodes and Processes — node/workspace allocation and durable external process steps.
• Pipeline: Stage View — optional visualization; not the source of Pipeline execution truth.