YAML Reuse with include, extends, Anchors, !reference, Hidden Jobs, and Template Architecture: Guided Hands-On Workflow and Core Operations

1. Disposable lab and preflight

Create a throwaway project named glci-ch12-reuse-lab and branch glci/ch12-reuse. The lab uses only local files for mandatory execution; the project-include portion is a safe simulation unless you already have a second disposable project you are authorized to use. No credentials, registry pushes, runners, cloud resources, or production namespaces are created.

2. Start with deliberate duplication so the refactor has a measurable target

Create two jobs that intentionally repeat image, setup, and variables. Run once and capture the pipeline/job IDs, source SHA, and successful output. This establishes behavior that the refactor must preserve.

stages: [test]

unit:
  stage: test
  image: alpine:3.20.3
  variables:
    TEST_MODE: unit
  before_script:
    - echo "prepare:$CI_COMMIT_SHA"
  script:
    - echo "run:$TEST_MODE"

integration:
  stage: test
  image: alpine:3.20.3
  variables:
    TEST_MODE: integration
  before_script:
    - echo "prepare:$CI_COMMIT_SHA"
  script:
    - echo "run:$TEST_MODE"

The duplication is small enough to understand. Do not optimize first; record the baseline final jobs first.

3. Extract a hidden template into a local include

Create ci/templates.yml. Because include:local reads from the same repository/revision, the dependency identity naturally travels with the source SHA.

# ci/templates.yml
.base_test:
  stage: test
  image: alpine:3.20.3
  before_script:
    - echo "prepare:$CI_COMMIT_SHA"
  variables:
    EVIDENCE_MODE: "chapter12"

# .gitlab-ci.yml
include:
  - local: /ci/templates.yml

stages: [test]

unit:
  extends: .base_test
  variables:
    TEST_MODE: unit
  script:
    - echo "run:$TEST_MODE:$EVIDENCE_MODE"

integration:
  extends: .base_test
  variables:
    TEST_MODE: integration
  script:
    - echo "run:$TEST_MODE:$EVIDENCE_MODE"

4. Inspect the expanded YAML before running

Use CI Lint or the pipeline editor’s expanded configuration. Verify that each job has the expected image, before_script, merged variables, and its own script. This is the core operational habit of the chapter: prove the compiled contract before relying on execution.

5. Compare a file-local anchor

Now create an anchor in the root file for one array. Anchors are convenient when the reused structure is truly local to one YAML document.

.common_steps: &common_steps
  - echo "sha=$CI_COMMIT_SHA"
  - echo "pipeline=$CI_PIPELINE_ID"

audit:
  image: alpine:3.20.3
  script:
    - *common_steps
    - echo "audit complete"

Move that anchor definition into ci/templates.yml while leaving the alias in the root file. Validation should fail because YAML anchors cannot cross file boundaries. Preserve the validation error as evidence, then restore the anchor to the same file.

6. Compare !reference for a cross-file array

For cross-file array reuse, define a named rules block in the include and select it explicitly.

# ci/templates.yml
.test_rules:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "push"'

# .gitlab-ci.yml
unit:
  extends: .base_test
  rules: !reference [.test_rules, rules]
  script:
    - echo "unit"

The expanded configuration should show the concrete rules array on unit. This makes the origin explicit without pretending arrays were appended by extends.

7. Observe a safe override and an unsafe assumption

First override one scalar/hash value deliberately:

unit:
  extends: .base_test
  image: alpine:3.20.3
  variables:
    TEST_MODE: unit
    EVIDENCE_MODE: "unit-override"
  script:
    - echo "$TEST_MODE:$EVIDENCE_MODE"

The child variable overrides only that variable while other parent variables remain. Next, add a child before_script expecting it to append. Inspect expanded YAML: the child array replaces the parent array. This is the deliberate lesson, not an error to hide.

8. Simulate a version-pinned project include

Model the configuration you would use for a second trusted GitLab project. Use a fake project path and a fake-looking but syntactically full SHA in the lesson; do not try to fetch it in the mandatory lab.

include:
  - project: 'training-ci/reuse-library'
    ref: '0123456789abcdef0123456789abcdef01234567'
    file: '/templates/base-test.yml' 

In a real authorized disposable setup, replace those values with the exact project and full commit SHA, then verify that the user creating the pipeline has sufficient access. Record the template project, SHA, and file path in the evidence packet.

9. Understand remote include integrity without making the lab depend on the internet

A remote include is fetched as an unauthenticated public HTTP(S) resource. Current GitLab supports an integrity value using a base64-encoded SHA-256. The safe pattern is to compute the reviewed file’s digest out of band and pin that digest in configuration.

include:
  - remote: 'https://example.invalid/ci/reviewed.yml'
    integrity: 'sha256-BASE64_SHA256_OF_REVIEWED_CONTENT' 

The example uses an intentionally non-routable documentation domain so it cannot mutate or depend on a real external system. Treat it as architecture, not as a runnable mandatory path.

10. Challenge: choose the right reuse layer

You have three repeated things: (a) two script lines in the same file, (b) a complete test-job template shared by files in the same repository, and (c) a versioned CI building block used by twenty projects. Choose the simplest mechanism for each and justify how you will prove the effective configuration and dependency identity.

A strong answer usually keeps (a) local with an anchor or direct duplication if trivial, uses a hidden job plus extends/!reference for (b), and moves (c) toward a versioned project include or, after Chapter 13, a CI/CD component with explicit inputs.

11. Cleanup and rollback

Delete only the disposable branch/project created for the lab after saving the evidence packet. No shared templates, protected refs, runners, or instance settings were changed. If you tested a second disposable project, remove only that exact project after confirming no other learner uses it.

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.