Checkpoint Lab — Jenkins and CI/CD Foundations, Controller-Agent Architecture, Jobs, Builds, and Automation Boundaries

1. Scenario and success criteria

You are handing a tiny CI job to another engineer. They must be able to answer, without guessing: which Jenkins baseline ran it, why each build existed, what exact source revision executed, which agent/workspace hosted the steps, what artifact bytes were retained, and whether any external deployment claim was actually verified. The checkpoint is successful only if those identities can be reconstructed after the live workspace is discarded.

2. Predict the state transitions before running

Write these predictions into ch01-predictions.md before creating the job:

1. A manual click will create a build with a user cause. The job will enter the queue, match label lab, allocate the single executor on lab-agent, create/reuse a workspace for this job, check out an immutable commit, run two stages, and archive files under out/.
2. After a new commit is pushed, the hashed SCM poll will detect a revision change and create a separate build with an SCM-trigger cause. Its build number and source SHA will differ; its agent label remains the same.
3. If the Jenkinsfile requests lab-missing, Jenkins will create/queue the build but no agent-executed step will begin.

You will verify each prediction independently rather than inferring it from the final build color.

3. Recreate or verify the pinned disposable baseline

If you still have the Lesson 2 controller, verify the exact names and versions before reusing it. Otherwise recreate it with the Lesson 2 commands. The dated baseline is:

4. Create the synthetic repository and Jenkinsfile

Create a new public disposable repository such as jenkins-ch01-checkpoint. Do not reuse an existing project. Add this Jenkinsfile:

pipeline {
  agent { label 'lab' }

  triggers {
    pollSCM('H/2 * * * *')
  }

  stages {
    stage('Observe') {
      steps {
        sh '''
          set -eu
          mkdir -p out
          SHA="$(git rev-parse HEAD)"
          {
            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' "$SHA"
            printf 'java='; java -version 2>&1 | head -n 1
          } | tee out/evidence.txt
        '''
      }
    }

    stage('Package evidence') {
      steps {
        sh '''
          set -eu
          printf 'checkpoint artifact\n' > out/payload.txt
          sha256sum out/evidence.txt out/payload.txt > out/SHA256SUMS
        '''
        archiveArtifacts artifacts: 'out/*', fingerprint: true
      }
    }
  }
}

Commit Jenkinsfile, README.md, and your ch01-predictions.md. Record the initial commit SHA locally before Jenkins ever runs it.

git rev-parse HEAD

5. Create the Pipeline from SCM

Create a Pipeline item named jenkins-ch01-checkpoint. Set Definition to Pipeline script from SCM, choose Git, use the disposable public repository URL, select the default branch, and set Script Path to Jenkinsfile. No repository credential should be required for a public read-only clone. Save the job.

Before clicking Build Now, inspect the job configuration once more and write down the repository URL, branch/ref, Jenkinsfile path, and requested agent label. This is the configuration state that will create the first run.

6. Run #1: manual cause and evidence chain

Click Build Now. Record the build number immediately. If it appears in the queue, capture the queue reason and then the transition to executor allocation. After completion, verify all of the following:

• The build cause identifies a user/manual action.
• The build ran on lab-agent, not the built-in node.
• The console and out/evidence.txt agree on job name, build number, node, workspace, and source SHA.
• The source SHA equals the repository commit you expected.
• out/SHA256SUMS and the archived artifacts are attached to this build record.
• The build has no production credential or external deployment side effect.

Download the artifact files into an evidence folder named with the Jenkins build number, for example evidence/build-1/.

7. Run #2: SCM change cause and immutable source identity

Make one harmless source change, such as adding a line to README.md, commit it, and push it. Record the new commit SHA. Wait for the hashed pollSCM schedule to detect the change. Do not click Build Now to “help” it, because that would change the cause you are trying to observe.

printf '\ncheckpoint-change: scm-trigger\n' >> README.md
git add README.md
git commit -m 'checkpoint: create SCM-triggered Jenkins build'
git push
git rev-parse HEAD

When the next build appears, verify that the build cause is SCM-related, the build number differs from Run #1, and source_sha equals the new commit. Download the new artifacts into a separate folder. The two evidence packets should be comparable without depending on the current state of the branch.

8. Failure injection: prove queue state is not script state

Create a third commit that changes the Pipeline label from lab to lab-missing. Predict that the SCM-triggered build will be created but remain waiting for an eligible node. After it appears, capture the queue/build reason before fixing anything.

Then restore the correct label in a fourth commit. Keep the queued/failure evidence; do not delete the run merely because it is inconvenient. If you choose to cancel it after capturing evidence, record that cancellation as a separate operator action.

9. Assemble the checkpoint evidence packet

Create a local folder containing:

• baseline.txt: Jenkins core/LTS, Java version, controller image tag/digest, relevant Pipeline plugin versions.
• agent.txt: node name, labels, executor count, inbound-agent image tag, Java/Remoting details.
• predictions.md: your pre-run predictions and whether each was confirmed.
• manual-build.md: build number/URL/cause/source SHA/node/workspace plus archived artifact hashes.
• scm-build.md: same fields for the SCM-triggered build.
• queue-failure.md: the missing-label build identity, queue reason, and least-destructive fix.
• Downloaded out/ artifacts from the successful runs.
• limitations.md: state clearly that this checkpoint does not prove production deployment health, secret-management quality, HA, plugin governance, or disaster recovery.

10. What each green state proves—and what it does not

11. Cleanup and rollback

First verify the exact disposable identities. Then remove the Jenkins item and agent if you no longer need them. Remove the named Docker resources only after exporting the evidence packet.

docker ps -a --filter name=jenkins-ch01
docker volume inspect jenkins-ch01-home
docker network inspect jenkins-ch01-net

# After evidence export and exact-name verification:
docker rm -f jenkins-ch01-agent jenkins-ch01-controller
docker network rm jenkins-ch01-net
docker volume rm jenkins-ch01-home

Delete the synthetic repository only after confirming its exact owner/name. Never use wildcard repository deletion or a script that selects “the latest” project.

12. Operational handoff and bridge to Chapter 02

The checkpoint demonstrates the minimum trustworthy Jenkins story: a known controller baseline, explicit agent boundary, two distinct build causes, immutable source identity, retained artifacts, a scheduling failure diagnosed at the correct layer, and exact cleanup. Chapter 02 will go deeper into installation choices, Java 21/25 runtime planning, package/container deployment models, initial setup, persistent state, exposure, and rollback.

Knowledge check

Official references and version notes

• Jenkins documentation — primary documentation hub.
• Jenkins Pipeline and Pipeline syntax — current Pipeline mental model and Declarative syntax.
• Java Support Policy — supported Java runtimes for Jenkins core, agents, and CLI components.
• Controller Isolation and Managing Nodes — controller/agent trust and executor guidance.
• Jenkins LTS changelog and Security advisories — current release/security state.
• Official Jenkins controller image and official inbound-agent image.