Checkpoint Lab — Includes, Templates, CI/CD Components, Component Catalog, and Reusable Pipeline Architecture

1. Checkpoint scenario and preflight

You will build a three-file reusable CI arrangement in one disposable Free project. It demonstrates same-commit local reuse, typed inputs, merged-configuration inspection, provenance recording, one deliberate contract failure, and cleanup. No real secret, external component, Catalog publication, deployment, registry deletion, or privileged runner is required.

2. Predict two state changes before touching the repository

Write these predictions first:

3. Create the reusable files

Create .gitlab/ci/ch20-template.yml:

.text_check:
  stage: test
  script:
    - test -n "$TARGET"
    - test -f "$TARGET"
    - wc -c "$TARGET"

Create .gitlab/ci/ch20-contract.yml:

spec:
  inputs:
    profile:
      options: [quick, full]
      default: quick
    emit_summary:
      type: boolean
      default: true
---
contract_check:
  stage: test
  script:
    - printf 'profile=%s summary=%s\n' '$[[ inputs.profile ]]' '$[[ inputs.emit_summary ]]'

Create two harmless fixtures:

mkdir -p labdata
printf 'api fixture\n' > labdata/api.txt
printf 'worker fixture\n' > labdata/worker.txt

4. Compose the main pipeline

stages: [test]

include:
  - local: .gitlab/ci/ch20-template.yml
  - local: .gitlab/ci/ch20-contract.yml
    inputs:
      profile: full
      emit_summary: true

api_check:
  extends: .text_check
  variables:
    TARGET: labdata/api.txt

worker_check:
  extends: .text_check
  variables:
    TARGET: labdata/worker.txt

Before linting, predict the final stage, script, and TARGET for api_check and worker_check, plus the interpolated input values for contract_check.

5. Validate and capture expanded configuration

PROJECT_ID="12345678"
mkdir -p evidence

jq --null-input --arg yaml "$(cat .gitlab-ci.yml)" '{content:$yaml}' \
| glab api --method POST "projects/$PROJECT_ID/ci/lint?include_merged_yaml=true" \
  --header "Content-Type: application/json" --input - \
  > evidence/ch20-lint.json

jq '{valid,errors,warnings}' evidence/ch20-lint.json
jq -r '.merged_yaml' evidence/ch20-lint.json > evidence/ch20-merged.yml

Verify: the lint response is valid and your predicted effective jobs match evidence/ch20-merged.yml.

6. Record dependency provenance before execution

git rev-parse HEAD > evidence/consumer-before.txt
git hash-object .gitlab-ci.yml .gitlab/ci/ch20-template.yml .gitlab/ci/ch20-contract.yml \
  > evidence/source-blob-ids.txt
sha256sum .gitlab-ci.yml .gitlab/ci/ch20-template.yml .gitlab/ci/ch20-contract.yml \
  > evidence/source-sha256.txt

The Git blob IDs identify repository content; SHA-256 provides an additional portable evidence digest. Neither proves trust by itself, but both make later comparisons precise.

7. Commit, push, and verify runtime identity

git switch -c ch20/checkpoint
git add .gitlab-ci.yml .gitlab/ci/ch20-template.yml .gitlab/ci/ch20-contract.yml labdata/ evidence/
git commit -m "lab: checkpoint reusable pipeline architecture"
git push -u origin ch20/checkpoint

git rev-parse HEAD

Inspect the resulting pipeline. Verify that all jobs belong to this SHA and that no external endpoint, registry, environment, or secret-bearing variable was introduced.

8. Deliberately break the typed contract

Change only the input value:

include:
  - local: .gitlab/ci/ch20-contract.yml
    inputs:
      profile: turbo
      emit_summary: true

turbo is outside the declared options. Run CI Lint again and preserve the validation error. This is the desired failure mode: configuration is rejected before a job can execute with an undefined policy.

9. Repair the smallest cause and re-verify

Restore profile: full (or add a deliberately reviewed new option in the contract with an appropriate compatibility decision). Lint again and compare the before/after errors and merged YAML. Do not add allow_failure; this is a configuration contract problem, not a runtime failure to suppress.

10. Convert the provenance record into a production dependency statement

Write a short dependency record such as:

dependency: platform/ci-components/verify
mechanism: include:component
consumer-policy: full semantic release
requested-version: 2.3.1
resolved-commit: <record exact reviewed SHA>
source-reviewed-by: <team/person>
runner-requirement: unprivileged
credentials-required: none
rollback: pin previous known-good release/SHA

This record is more operationally useful than “we use the shared template.”

11. Optional Catalog design review

Without enabling anything, verify whether a future component project would satisfy current publication prerequisites: project description, root README, templates/, tests, semantic tag, release job, Catalog-project setting, Owner to enable the setting, and Maintainer/Owner for publication. Treat the experimental glab repo publish catalog command as optional until your instance explicitly supports it.

12. Cleanup and rollback

Keep the evidence files if they are useful learning records. Remove synthetic branch/project resources only after verification.

git switch main
# Inspect before destructive remote deletion.
git ls-remote --heads origin ch20/checkpoint
# If and only if this is your disposable lab branch:
# git push origin --delete ch20/checkpoint
git branch -D ch20/checkpoint 2>/dev/null || true

If you created an optional disposable component project, record its final SHA and consumers first, then delete the project through the UI/API only if no other project depends on it.

13. What Chapter 20 adds to the production GitLab operating model

Your pipeline model now has an explicit software-supply layer: reusable CI code has owners, typed interfaces, immutable provenance, tests, release compatibility, least-privilege execution, consumer migration, and rollback. Chapter 21 will use that model to optimize execution safely—interrupting obsolete work, retrying intentionally, debugging failures, and controlling pipeline cost without destroying evidence.

Knowledge check

Summary

You built, inspected, broke, repaired, and documented a reusable pipeline dependency without paid features or live external infrastructure. The durable production pattern is: small contract, explicit owner, merged-config inspection, immutable provenance, representative tests, least privilege, compatible releases, and a known rollback.

Official references

Primary sources used for the current GitLab 19.3 behavior taught in this lesson:

• GitLab Docs — Use CI/CD configuration from other files
• GitLab Docs — CI/CD components
• GitLab Docs — CI/CD inputs
• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — CI Lint API
• GitLab CLI — glab repo publish catalog (experimental)