Checkpoint Lab — GitLab CI/CD Foundations: .gitlab-ci.yml, Pipelines, Jobs, Stages, and Execution Model

1. Checkpoint mission

You are onboarding a repository to GitLab CI/CD. The production requirement is intentionally small: prove which commit ran, preserve a tiny evidence artifact, and demonstrate that the team can diagnose one failed job without weakening policy. Nothing may deploy, publish, push another repository, call a cloud account, or expose a token.

Use a disposable project or branch. The checkpoint is complete when another engineer can read your evidence and explain why the pipeline existed, what SHA it tested, what order the jobs followed, which runner executed them, why the injected failure occurred, and how you proved cleanup.

2. Preflight and assumptions

3. Prediction ledger — write this before pushing

Assume the lab branch is ch10/checkpoint and the push commit SHA is S. Record your predictions first:

1. Pipeline source: a direct Git push should create a push pipeline unless creation rules say otherwise.
2. Commit identity: CI_COMMIT_SHA should equal S and git rev-parse HEAD inside the job.
3. Order: capture in stage inspect must succeed before verify in stage verify becomes eligible.
4. Runner: an untagged job can run only if an available runner is eligible for untagged work under project policy.
5. Artifact: only checkpoint-evidence.txt should be uploaded; no secret variable value should be included.

4. Baseline pipeline

Create .gitlab-ci.yml with two jobs. The second job verifies the checkout and artifact content but makes no external change.

stages:
  - inspect
  - verify

capture:
  stage: inspect
  script:
    - printf 'source=%s\n' "$CI_PIPELINE_SOURCE" | tee checkpoint-evidence.txt
    - printf 'sha=%s\n' "$CI_COMMIT_SHA" | tee -a checkpoint-evidence.txt
    - printf 'job=%s\n' "$CI_JOB_ID" | tee -a checkpoint-evidence.txt
    - printf 'runner=%s\n' "${CI_RUNNER_ID:-unknown}" | tee -a checkpoint-evidence.txt
    - test -n "${CI_JOB_TOKEN:-}"
    - printf 'job_token=present-not-printed\n' | tee -a checkpoint-evidence.txt
  artifacts:
    paths:
      - checkpoint-evidence.txt
    expire_in: 1 day

verify:
  stage: verify
  script:
    - test "$CI_COMMIT_SHA" = "$(git rev-parse HEAD)"
    - printf 'verified_sha=%s\n' "$CI_COMMIT_SHA"
    - printf 'external_side_effects=none\n' 

5. Validate, commit, and identify the exact pipeline

Validate in Pipeline Editor/CI Lint first. Then commit on the disposable branch and record the SHA before push.

REPO="GROUP/ch10-ci-foundations"
LAB_BRANCH="ch10/checkpoint"
mkdir -p ch10-checkpoint-evidence

git switch -c "$LAB_BRANCH"
git add -- .gitlab-ci.yml
git diff --cached --check
git diff --cached
git commit -m "ch10: checkpoint pipeline"
S="$(git rev-parse HEAD)"
printf '%s\n' "$S" | tee ch10-checkpoint-evidence/expected-sha.txt
git push -u origin "$LAB_BRANCH"

glab ci list -R "$REPO" --ref "$LAB_BRANCH" --output json --per-page 10   --jq '.[] | {id,status,source,ref,sha,web_url}'   | tee ch10-checkpoint-evidence/pipelines-baseline.json

6. Verify the baseline independently

Do not accept “green” alone. Check all of the following:

• The newest intended pipeline has source=push, ref=ch10/checkpoint, and sha=S.
• capture completed before verify became eligible under stage ordering.
• The log shows runner metadata and job_token=present-not-printed, never the token itself.
• The verify job proves git rev-parse HEAD == CI_COMMIT_SHA.
• The artifact contains only the synthetic fields you predicted.

glab ci status -R "$REPO" --branch "$LAB_BRANCH" --compact
glab ci get -R "$REPO" --branch "$LAB_BRANCH" --output json --with-job-details   | tee ch10-checkpoint-evidence/pipeline-detail.json

git fetch origin "$LAB_BRANCH"
printf 'expected=%s remote=%s\n' "$S" "$(git rev-parse FETCH_HEAD)"

7. Inject one safe failure without changing permissions

Now modify only the verify job. Add a deterministic failing assertion after the correct SHA check:

verify:
  stage: verify
  script:
    - test "$CI_COMMIT_SHA" = "$(git rev-parse HEAD)"
    - echo "intentional checkpoint failure follows"
    - test "expected" = "intentionally-different"

8. Preserve the failure, identify the causal line, then repair it

Commit/push the failure and capture the new SHA F. Inspect the failed job log before changing anything. The original cause must remain visible in evidence.

git add -- .gitlab-ci.yml
git commit -m "ch10: inject deterministic checkpoint failure"
F="$(git rev-parse HEAD)"
printf '%s\n' "$F" | tee ch10-checkpoint-evidence/failing-sha.txt
git push

glab ci list -R "$REPO" --ref "$LAB_BRANCH" --status failed --output json --per-page 5   --jq '.[] | {id,status,source,ref,sha}'   | tee ch10-checkpoint-evidence/failed-pipelines.json

# Inspect the failed job in UI or glab ci get/trace.
glab ci get -R "$REPO" --branch "$LAB_BRANCH" --with-job-details

# Repair only the deliberately false assertion.
# Restore the verify job to:
verify:
  stage: verify
  script:
    - test "$CI_COMMIT_SHA" = "$(git rev-parse HEAD)"
    - printf 'verified_sha=%s\n' "$CI_COMMIT_SHA"
    - printf 'external_side_effects=none\n' 

9. Prove the repair is a new commit and new pipeline

Commit the repair, record SHA R, push, and confirm the successful pipeline is tied to R. Do not overwrite or delete the failed pipeline just to make history look clean—the failed run is useful evidence that the diagnostic process worked.

git add -- .gitlab-ci.yml
git commit -m "ch10: repair checkpoint assertion"
R="$(git rev-parse HEAD)"
printf '%s\n' "$R" | tee ch10-checkpoint-evidence/repaired-sha.txt
git push

glab ci status -R "$REPO" --branch "$LAB_BRANCH" --wait
glab ci list -R "$REPO" --ref "$LAB_BRANCH" --output json --per-page 10   --jq '.[] | {id,status,source,ref,sha}'   | tee ch10-checkpoint-evidence/pipelines-final.json

10. Security and side-effect verification

Search only your saved evidence and synthetic artifact for forbidden content. You are checking that the job printed a fixed presence message rather than a token value.

# Local evidence scan; patterns are intentionally conservative.
if grep -RniE 'glpat-|PRIVATE-TOKEN:|Authorization: Bearer|CI_JOB_TOKEN=' ch10-checkpoint-evidence; then
  echo "Review the matching line before sharing evidence."
else
  echo "No obvious credential-shaped output found in saved evidence."
fi

# Review the repository diff: only .gitlab-ci.yml should be synthetic.
git show --stat --oneline "$R"
git diff "${S}^".."$R" -- .gitlab-ci.yml

11. Cleanup/rollback

Only after evidence capture, remove the lab branch or revert the synthetic CI file. Verify the remote pointer before deletion so you do not target the wrong branch.

git fetch origin --prune
REMOTE_LAB_SHA="$(git rev-parse "origin/$LAB_BRANCH")"
printf 'remote_lab_sha=%s\n' "$REMOTE_LAB_SHA"
git log --oneline --decorate -n 5 "origin/$LAB_BRANCH"

# If this branch is confirmed disposable:
git push origin --delete "$LAB_BRANCH"
git fetch origin --prune

# Prove the remote branch is gone; no output is expected.
git ls-remote --heads origin "$LAB_BRANCH"

12. Checkpoint verification checklist

• ☐ CI Lint/Editor accepted the baseline configuration before commit.
• ☐ Pipeline source/ref/SHA matched the prediction.
• ☐ Stage order matched inspect → verify.
• ☐ Runner identity was recorded without runner credential exposure.
• ☐ CI_JOB_TOKEN presence was verified without printing its value.
• ☐ The baseline artifact contained only synthetic metadata.
• ☐ The deliberate failure preserved a failed pipeline/job and causal log line.
• ☐ Repair changed only the failing assertion and produced a new successful pipeline on a new SHA.
• ☐ No external system was changed.
• ☐ The lab ref/configuration was removed or intentionally retained with documented purpose.

13. What Chapter 10 adds to the production operating model

You can now reason about GitLab CI/CD as a chain of inspectable resources rather than a YAML-triggered black box. The operating model has gained: versioned CI configuration, creation-time source/ref/SHA identity, explicit stage/job state, runner/executor trust boundaries, short-lived job identity, log/artifact evidence, and a failure taxonomy that points to the correct subsystem.

Chapter 11 moves inside the job definition itself: scripts, images, services, before_script, after_script, defaults, shell behavior, and image provenance. The mental model from this chapter is the prerequisite—you must know when and where a job executes before optimizing what it executes.

Knowledge check

Summary

The checkpoint established a repeatable CI operating discipline: predict → validate → bind to SHA → run/simulate → inspect pipeline/job/runner evidence → inject a bounded failure → preserve the cause → repair only the cause → verify security/side effects → clean up. That discipline scales to the more advanced GitLab CI/CD mechanisms that follow.

Official references

• GitLab Docs — CI/CD
• GitLab Docs — Get started with GitLab CI/CD
• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Validate CI/CD configuration
• GitLab Docs — Pipeline editor
• GitLab Docs — Pipelines
• GitLab Docs — CI/CD jobs
• GitLab Docs — Job execution flow
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — CI/CD variables
• GitLab Docs — CI/CD job token
• GitLab Docs — Runners
• GitLab Docs — Configure runners
• GitLab Docs — GitLab-hosted runners
• GitLab Docs — Pipelines API
• GitLab Docs — Jobs API
• GitLab Docs — CI Lint API
• GitLab Docs — Job rules and CI_PIPELINE_SOURCE
• GitLab CLI — ci
• GitLab CLI — ci list
• GitLab CLI — ci get
• GitLab CLI — ci status
• GitLab CLI — runner list