Checkpoint Lab — Source Control Integration, Git Plugin, Credentials, Polling, Webhooks, and Multirepository Checkout

1. Checkpoint scenario

You are onboarding a synthetic application repository to Jenkins. The controller and linux agent are disposable. The repository is served by the local lab Git service from Lesson 2. Your task is to trigger a build from a controlled source change, prove the exact source revision and cause, show that no unnecessary SCM credential is attached, then introduce and diagnose one source-selection or trigger-path defect.

The final deliverable is not merely a green build. It is a reviewed evidence packet that lets another engineer reconstruct what repository Jenkins read, why it scheduled the build, which commit executed, which agent/toolchain performed checkout, and which configuration defect you introduced and repaired.

2. Preflight and predictions

Before making changes, record:

• Jenkins 2.568.3 LTS and Java runtime.
• Git plugin 5.10.1, Git Client 6.6.1, Credentials 1511.v2e3cb_0008ef0.
• Agent name/label and git --version.
• Synthetic APP_URL and current remote main SHA.
• Job full name scm-checkpoint and current trigger configuration.
• SCM credential selection: none for the unauthenticated lab repository.

Write two predictions before acting:

1. After pushing one controlled commit and invoking the token-protected notification, Jenkins should poll the matching repository and schedule at most the expected build path for the new revision.
2. The successful checkout should produce a workspace HEAD equal to the new remote main SHA; archiving the evidence file should not change source identity.

3. Configure the checkpoint job

Create scm-checkpoint as a Freestyle project restricted to linux. Configure Git SCM with the synthetic application URL, no credential, and branch specifier */main. Enable Poll SCM but leave the schedule blank so the Git plugin can respond to notifyCommit without creating a recurring poll timer.

Add a shell step that writes reviewed source evidence:

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 'git_plugin_commit=%s\n' "${GIT_COMMIT:-unset}"
  printf 'remote=%s\n' "$(git remote get-url origin)"
  printf 'head=%s\n' "$(git rev-parse HEAD)"
  printf 'git_version=%s\n' "$(git --version)"
  git show -s --format='commit_time=%cI%nsubject=%s' HEAD
} > evidence/source.txt
sha256sum evidence/source.txt > evidence/source.txt.sha256
cat evidence/source.txt

Archive evidence/*. Do not dump all environment variables. The goal is a minimal, reviewable evidence packet rather than a secret-rich forensic snapshot.

4. Create and record a controlled commit

LAB_ROOT="$HOME/jenkins-scm-lab"
printf 'checkpoint %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"   >> "$LAB_ROOT/writer/app/README.txt"
git -C "$LAB_ROOT/writer/app" add README.txt
git -C "$LAB_ROOT/writer/app" commit -m "checkpoint: controlled change"
git -C "$LAB_ROOT/writer/app" push origin main
EXPECTED_SHA="$(git -C "$LAB_ROOT/writer/app" rev-parse HEAD)"
printf 'expected_sha=%s\n' "$EXPECTED_SHA"

Save EXPECTED_SHA in your local checkpoint notes. It is synthetic source evidence and safe to retain.

5. Trigger through the protected notification path

Use the lab-only Git plugin notifyCommit token created earlier. Keep it outside logs and evidence.

export JENKINS_URL='http://127.0.0.1:8080'
export APP_URL='git://127.0.0.1:9418/app.git'
TOKEN_FILE="$HOME/.jenkins-scm-lab-notify-token"
umask 077
read -rsp 'Lab notifyCommit token: ' token; printf '\n'
printf '%s' "$token" > "$TOKEN_FILE"
unset token

curl --fail --get   --data-urlencode "url=$APP_URL"   --data-urlencode "token@$TOKEN_FILE"   "$JENKINS_URL/git/notifyCommit"   > notify-response.txt
rm -f "$TOKEN_FILE"

# Review locally; ensure the token itself is not present before retention.
cat notify-response.txt

Capture the Jenkins polling log, resulting queue/build ID, build cause, and console log. When the build completes, download or inspect evidence/source.txt and compare head=... against EXPECTED_SHA.

6. Verify the evidence chain

7. Fault option A: wrong branch/ref

Create a second branch in the synthetic repository, then intentionally set the Jenkins branch specifier to that branch while expecting main. Trigger a manual diagnostic build and observe that the workspace SHA differs from the main expectation. Preserve the build before fixing the branch specifier.

LAB_ROOT="$HOME/jenkins-scm-lab"
git -C "$LAB_ROOT/writer/app" switch -c diagnostic-wrong-ref
printf 'diagnostic branch\n' >> "$LAB_ROOT/writer/app/README.txt"
git -C "$LAB_ROOT/writer/app" add README.txt
git -C "$LAB_ROOT/writer/app" commit -m "diagnostic: wrong-ref evidence"
git -C "$LAB_ROOT/writer/app" push -u origin diagnostic-wrong-ref
git -C "$LAB_ROOT/writer/app" switch main

Diagnosis must state that Jenkins behaved according to configuration: the defect was the branch selection, not “Git randomly checked out the wrong commit.” Correct the branch specifier, then run the smallest verification build and compare SHAs.

8. Fault option B: duplicate trigger path

Alternatively, add a temporary H/5 * * * * Poll SCM schedule while continuing to call notifyCommit. Push one controlled change and capture all polling/notification/build evidence for a short bounded window. If you observe redundant polling or duplicate build behavior, explain the timing from logs. Then remove the schedule and leave the notification-triggered polling path only.

9. Credential-scope proof

The checkpoint repository is intentionally unauthenticated inside the disposable lab, so the correct SCM credential scope is none. Capture a screenshot-free textual note such as “SCM Credentials field: - none -” and the sanitized job configuration showing no credential ID. That is stronger least-privilege evidence than inventing a secret requirement.

Optional protected-repository extension: use a fake account on a disposable local Git service and a folder-scoped read-only credential. The evidence packet records only the credential ID/scope and successful checkout—not the secret value.

10. Evidence packet manifest

Never include a notify token, API token, private key, credential export, full environment dump, or proprietary repository data.

11. Cleanup and rollback

1. Remove the temporary polling schedule if fault option B was used.
2. Restore */main if fault option A was used.
3. Confirm the final verification build resolves to the expected main SHA.
4. Preserve only the reviewed evidence packet.
5. Delete scm-checkpoint only after confirming its exact full name and that it was created for this lab.
6. Stop the lab Git service and remove only the synthetic lab directories.
7. Delete the lab notifyCommit token if it was created solely for this course exercise; do not modify global plugin access-control settings.

12. What Chapter 06 adds to the Jenkins operating model

You can now prove source identity rather than merely naming a branch. Jenkins SCM integration becomes an auditable chain: repository and credential intent → polling/notification cause → plugin/tool resolution → exact checkout → workspace/changelog evidence → downstream build. That foundation is required before Chapter 07 adds richer build parameters, environment variables, schedules, remote triggers, and parameterized automation.

Knowledge check

Official references and version notes

• Jenkins LTS changelog — current LTS release and tested Java configurations.
• Git plugin — repositories, credentials, polling, push notifications, checkout behavior, environment variables, and plugin security notes.
• Git Client plugin — command-line/JGit implementations and SSH host-key verification strategies.
• scmGit Pipeline reference — explicit Git checkout configuration and supported checkout capabilities.
• Credentials security — limiting credential access and protecting secrets.
• Using credentials — credential kinds, stores, scope, and Jenkins usage.
• Controller Isolation — why routine checkout/build execution belongs on agents.
• Using a Jenkinsfile — Pipeline checkout and credential-handling patterns.