Checkpoint Lab — YAML Reuse with include, extends, Anchors, !reference, Hidden Jobs, and Template Architecture

1. Checkpoint scenario and acceptance criteria

You inherit a pipeline with three nearly identical validation jobs. Refactor it so duplication is reduced using (1) a local included hidden job plus extends, and (2) a reusable rules array selected with !reference. Prove from expanded configuration that all intended final jobs remain equivalent in image/stage/rules/setup, while job-specific scripts remain explicit.

Then deliberately break one inheritance edge by overriding an array, preserve the failed evidence, repair it without hiding the root cause, and document how the same template would be pinned if moved to a shared project.

2. Preflight and assumptions

• Disposable project glci-ch12-checkpoint and branch glci/ch12-checkpoint.
• GitLab Free-compatible core syntax; current GitLab behavior verified 2026-09-11.
• Any ordinary trusted runner; no privileged execution, cloud account, registry, or production credentials.
• CI Lint/pipeline editor available for merged/expanded configuration inspection.
• If no runner exists, completing compilation/expanded-YAML evidence plus local shell simulation is an accepted faithful path; label runtime fields “not observed.”

3. Predict state changes before editing

4. Create the reusable local template

# ci/checkpoint.yml
.validation_base:
  stage: test
  image: alpine:3.20.3
  before_script:
    - echo "prepare:$CI_COMMIT_SHA"
    - mkdir -p evidence
  variables:
    CH12_CONTRACT: "v1"

.validation_rules:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "push"' 

The hidden job is the hash-like job template. The separate hidden rules object is selected explicitly rather than relying on array merging.

5. Build the root configuration

include:
  - local: /ci/checkpoint.yml

stages: [test]

lint_config:
  extends: .validation_base
  rules: !reference [.validation_rules, rules]
  script:
    - echo "lint:$CH12_CONTRACT" | tee evidence/lint.txt
  artifacts:
    when: always
    paths: [evidence/]
    expire_in: 1 day

unit_config:
  extends: .validation_base
  rules: !reference [.validation_rules, rules]
  script:
    - echo "unit:$CH12_CONTRACT" | tee evidence/unit.txt
  artifacts:
    when: always
    paths: [evidence/]
    expire_in: 1 day

integration_config:
  extends: .validation_base
  rules: !reference [.validation_rules, rules]
  script:
    - echo "integration:$CH12_CONTRACT" | tee evidence/integration.txt
  artifacts:
    when: always
    paths: [evidence/]
    expire_in: 1 day

6. Validate and capture the compiled contract before execution

Run CI Lint and inspect the expanded configuration. Save a text/PDF/screenshot-equivalent evidence note containing:

• source SHA and branch,
• root include path,
• the fully expanded keys for all three jobs,
• resolved rules, image, before_script, variables, script, and artifacts,
• the validation result and timestamp.

If your GitLab provides pipeline simulation, use it to confirm expected jobs for a push. Validation success proves configuration shape, not runner execution or artifact upload.

7. Run once and capture runtime evidence

Push the disposable branch. Record pipeline source/ref/SHA, pipeline ID, each job ID/status, runner ID/version/executor, and the three small evidence artifacts. Do not store secrets in the artifacts.

printf 'source=%s
ref=%s
sha=%s
pipeline=%s
job=%s
runner=%s
'   "$CI_PIPELINE_SOURCE" "$CI_COMMIT_REF_NAME" "$CI_COMMIT_SHA"   "$CI_PIPELINE_ID" "$CI_JOB_ID" "${CI_RUNNER_ID:-unknown}"

8. Deliberately break one inheritance edge

Change only unit_config:

unit_config:
  extends: .validation_base
  rules: !reference [.validation_rules, rules]
  before_script:
    - echo "unit-only-setup"
  script:
    - test -d evidence
    - echo "unit:$CH12_CONTRACT" | tee evidence/unit.txt

Predict the result before running: the child before_script replaces the parent array, so evidence/ is not created and the first test -d evidence fails. Preserve the expanded job showing the replacement and the first failing job trace.

9. Repair the causal configuration, not the symptom

Do not add mkdir -p evidence into the job’s script merely to make it pass; that would hide the inheritance misunderstanding. Remove the child before_script override, or define a deliberately reusable setup array and reference it explicitly. Then create a new pipeline and prove the expanded configuration again.

10. Model the shared-project promotion path

If ci/checkpoint.yml later moves to a shared project, document this reviewed consumer form:

include:
  - project: 'platform/ci-library'
    ref: 'fedcba9876543210fedcba9876543210fedcba98'
    file: '/templates/validation.yml' 

The exact project path and SHA become part of the reusable dependency evidence. Chapter 13 will turn this idea into a versioned component/interface model with explicit inputs.

11. Required evidence packet

12. Verification checklist and cleanup

• Exactly three intended jobs exist for the chosen pipeline source.
• All three expanded jobs have the same intended image/stage/setup/contract variable.
• Each job’s script remains explicit and unique.
• The deliberate failure is explained by array replacement, not runner state.
• The repaired pipeline restores the parent setup and succeeds without unrelated changes.
• No real token, secret, privileged runner, production URL, registry, or external deployment appears anywhere.

After saving the evidence packet, delete only the disposable branch/project created for this lab.

13. What Chapter 12 adds to the production operating model

You can now treat shared YAML as executable, versioned operational code: its provenance is explicit, its merge contract is inspectable, and failures are diagnosed from the compiled configuration. Chapter 13 builds on this foundation with CI/CD components, the Component Catalog, typed inputs, versioned reuse, and organization-wide building blocks.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-11. CI reuse and include behavior evolves across GitLab releases, especially include subkeys, integrity/caching, inputs/components, and template deprecations. Re-check the deployed GitLab version before relying on newer include features on Self-Managed or Dedicated installations.

• CI/CD YAML syntax reference — current include types/subkeys, merge behavior, extends, hidden jobs, defaults, and pipeline syntax.
• Use CI/CD configuration from other files — local/project/remote/template include behavior, variables, rules, overrides, troubleshooting, and trust guidance.
• Optimize GitLab CI/CD configuration files — anchors, hidden jobs, extends, reverse deep merge, and !reference.
• Pipeline editor — validation and expanded configuration showing includes, anchors, extends, and !reference resolved.
• CI Lint — validate and simulate configuration before creating a real pipeline.
• CI/CD inputs — typed configuration interfaces that become increasingly important in Chapter 13.