Checkpoint Lab — CI/CD YAML, Scripts, Images, Services, before_script, after_script, and Defaults

1. Checkpoint mission

You are standardizing the first reusable runtime conventions for a small GitLab project. The policy must show exactly how defaults propagate, how job-specific overrides behave, how lifecycle hooks execute, which image/service dependency is used, and how a failure is diagnosed. The lab must not deploy, publish packages, mutate a registry, access production infrastructure, or expose credentials.

2. Preflight and required assumptions

3. Prediction ledger — write it before the first push

Before execution, record at least these predictions:

1. inspect_runtime inherits the default image, default before_script, and default after_script.
2. verify_override inherits the default image but replaces before_script and disables after_script.
3. The main script can see a variable exported by the inherited default before_script; after_script cannot.
4. A file written in the checkout can still be read by after_script because filesystem state persists even though shell state does not.
5. If the optional service job is used, it reaches the sidecar as web, not localhost, and must wait for readiness.

4. Baseline two-job pipeline

default:
  image: alpine:3.22
  before_script:
    - echo "01 default before"
    - export SESSION_MARKER="main-shell-only"
  after_script:
    - echo "90 default after"
    - test -z "${SESSION_MARKER:-}"
    - test -f checkpoint-state.txt
    - cat checkpoint-state.txt

stages: [inspect, verify]

inspect_runtime:
  stage: inspect
  script:
    - echo "10 inspect script"
    - test "$SESSION_MARKER" = "main-shell-only"
    - test "$CI_COMMIT_SHA" = "$(git rev-parse HEAD)"
    - printf 'sha=%s
' "$CI_COMMIT_SHA" > checkpoint-state.txt
    - printf 'image=%s
' "${CI_JOB_IMAGE:-not-reported}" >> checkpoint-state.txt
    - printf 'side_effects=none
' >> checkpoint-state.txt
  artifacts:
    paths: [checkpoint-state.txt]
    expire_in: 1 day

verify_override:
  stage: verify
  before_script:
    - echo "02 override before"
  script:
    - echo "20 verify script"
    - test -z "${SESSION_MARKER:-}"
    - test "$CI_COMMIT_SHA" = "$(git rev-parse HEAD)"
  after_script: []

5. Validate, commit, and bind the run to an exact SHA

Validate in Pipeline Editor/CI Lint before commit. Then use the disposable branch, inspect the staged diff, and record the SHA.

LAB_BRANCH="ch11/checkpoint"
mkdir -p ch11-checkpoint-evidence
git switch -c "$LAB_BRANCH"
git add -- .gitlab-ci.yml
git diff --cached --check
git diff --cached
git commit -m "ch11: checkpoint CI runtime semantics"
BASELINE_SHA="$(git rev-parse HEAD)"
printf '%s
' "$BASELINE_SHA" | tee ch11-checkpoint-evidence/baseline-sha.txt
git push -u origin "$LAB_BRANCH"

6. Verify the baseline independently

• ☐ Pipeline/job metadata SHA equals BASELINE_SHA.
• ☐ inspect_runtime log shows markers 01 → 10 → 90 in lifecycle order.
• ☐ Main script sees SESSION_MARKER; after script proves it is absent in the fresh shell.
• ☐ after_script can read checkpoint-state.txt.
• ☐ verify_override shows marker 02 but not marker 01 or 90.
• ☐ No credential value, production URL, package publication, or deployment occurs.

7. Optional live service extension (container-capable runner only)

Add this third job only if the runner supports services. Otherwise validate it as a fixture and explain why the executor boundary prevents live execution.

service_contract:
  stage: verify
  image: alpine:3.22
  services:
    - name: nginx:1.28-alpine
      alias: web
  before_script: []
  script:
    - |
      n=1
      while [ "$n" -le 10 ]; do
        if wget -qO- http://web/ >/dev/null; then
          echo "service_ready_attempt=$n"
          exit 0
        fi
        n=$((n + 1))
        sleep 1
      done
      echo "service readiness timeout" >&2
      exit 1
  after_script: []

8. Inject one bounded failure and predict the evidence

Break verify_override with a deterministic shell assertion. Do not change runner tags, credentials, project settings, or failure policy.

verify_override:
  stage: verify
  before_script:
    - echo "02 override before"
  script:
    - echo "20 verify script"
    - test -z "${SESSION_MARKER:-}"
    - echo "intentional checkpoint failure follows"
    - test "expected" = "different"
  after_script: []

9. Preserve the failed state before repair

Commit/push the broken configuration and record FAILED_SHA. Save the failed pipeline ID/job ID and the log line surrounding the false assertion. Do not erase the failure by retrying with modified permissions or adding allow_failure.

git add -- .gitlab-ci.yml
git commit -m "ch11: inject deterministic runtime failure"
FAILED_SHA="$(git rev-parse HEAD)"
printf '%s
' "$FAILED_SHA" | tee ch11-checkpoint-evidence/failed-sha.txt
git push
# In GitLab UI or current glab ci commands, record pipeline/job IDs and failed log evidence.

10. Repair only the causal layer

Remove the deliberately false comparison and restore the correct assertions. Commit as REPAIRED_SHA, run again, and compare the three states: baseline, failed, repaired.

11. Pin or record runtime dependencies

Before closing the checkpoint, record the image references used by the job. If the runner/registry exposes the resolved digest, preserve it in evidence. In a production pipeline, prefer a reviewed digest or internally promoted immutable reference where exact identity matters. Do not paste a made-up digest into the YAML.

If you used the optional NGINX service, record its image reference separately from the job image; they are independent supply-chain dependencies.

12. Cleanup and rollback

Cleanup must be scoped to the synthetic resources. Preserve evidence first, then remove the lab branch or revert the CI commit if the project must remain. Do not delete a shared project, change runner registration, or modify group policy as part of this checkpoint.

# After evidence capture and after confirming you are on a safe branch:
git switch main
git pull --ff-only
# Optional for a disposable lab branch:
git push origin --delete ch11/checkpoint
git branch -D ch11/checkpoint

13. Final verification checklist

• ☐ Exact curriculum title/path and disposable branch were used.
• ☐ Baseline, failed, and repaired commit SHAs are recorded.
• ☐ Resolved default/override behavior is proven by ordered log markers.
• ☐ Main-shell versus after-shell state is proven without printing secrets.
• ☐ Image/service references and available digest evidence are recorded.
• ☐ Optional service used an alias and bounded readiness check.
• ☐ Failure was repaired at the script/readiness layer without allow_failure, privilege escalation, or policy bypass.
• ☐ No external system was changed and synthetic resources were removed or intentionally retained with documentation.

14. What Chapter 11 adds to the production operating model

The GitLab operating model now extends from pipeline/job identity into the runtime contract itself: resolved defaults, executor capability, explicit image and service dependencies, shell/lifecycle boundaries, working-directory behavior, exit-code semantics, and dependency provenance. You can distinguish “configuration said this” from “runner executed this,” and you can prove the difference.

Chapter 12 adds the next control layer: rules, workflow, pipeline sources, changes/conditions, and dynamic pipeline creation. That chapter decides whether a pipeline or job is created; this chapter established what happens inside the job once it exists.

Knowledge check

Summary

The checkpoint proved a production-grade learning loop for CI runtime configuration: predict resolved YAML → validate → bind to SHA → observe lifecycle and executor evidence → inject a bounded failure → preserve the original cause → repair only the causal layer → record dependency identity → verify no secret/external side effect → clean up. That foundation is essential before adding conditional pipeline creation in Chapter 12.

Official references

• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Scripts and job logs
• GitLab Docs — Deprecated CI/CD keywords
• GitLab Docs — Use CI/CD configuration from other files
• GitLab Docs — Run CI/CD jobs in Docker containers
• GitLab Docs — Services
• GitLab Docs — Docker executor
• GitLab Docs — Shell executor
• GitLab Docs — Runner executors
• GitLab Docs — Pipeline editor
• GitLab Docs — CI Lint
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — Runner security