YAML Reuse with include, extends, Anchors, !reference, Hidden Jobs, and Template Architecture: Configuration, Design Choices, and Tradeoffs

1. Reuse architecture is an ownership and trust decision

The shortest YAML is not necessarily the best reusable architecture. Every abstraction adds an owner, compatibility promise, failure mode, and upgrade path. Decide first who owns the reusable code, who may change it, who consumes it, and how a consumer can pin/roll back it.

2. Local vs project vs remote vs template

3. extends vs anchors vs !reference

Prefer readability over clever nesting. A small amount of obvious duplication can be safer than a four-layer inheritance chain whose effective behavior requires specialist knowledge.

4. Design around array replacement explicitly

Scripts, tags, services, and rules are often arrays. If a child defines the same array key, do not assume it appends to the parent. Make replacement intentional or select reusable arrays with !reference/anchors where appropriate.

.base:
  script:
    - echo "parent"

child:
  extends: .base
  script:
    - echo "child"  # effective script is only this array

5. Deep inheritance is a maintainability cost

GitLab can resolve up to eleven levels of extends inheritance, but the documentation recommends avoiding more than three. The limit is not a design target. Each layer increases the number of files/definitions a reviewer must mentally compose and makes array replacement or nulling harder to see.

Use one or two semantic layers—such as .base_test and .python_test—then prefer explicit job configuration for the final differences.

6. Moving refs trade convenience for reproducibility

A branch such as main makes upgrades automatic but also changes consumers without a consumer-side review. A protected release tag narrows who can move the version name; a full commit SHA is the strongest immutable identity. For critical shared pipeline logic, pin the immutable revision and upgrade through a normal review.

7. Remote include needs integrity and upstream review

include:remote cannot authenticate to the URL. That makes it unsuitable for private template retrieval and raises supply-chain questions. Current GitLab supports include:integrity for SHA-256 verification of remote content. Integrity proves content bytes match the expected digest; it does not tell you that those bytes are good. You still need an upstream review/release process.

8. Define what callers may override

A template should document required variables/inputs, default image, stages, rules, artifacts, side effects, and which keys consumers may override. Without a contract, consumers depend on internal details and template maintainers cannot change implementation safely.

For simple YAML reuse, comments and documentation can express the contract. Chapter 13 introduces CI/CD components and typed inputs, which formalize this idea further.

9. Treat included CI as code with runner-level authority

An included template can add scripts, images, services, artifacts, network calls, or deployment jobs. If a consuming project has protected variables or privileged runners, a malicious template change can exercise those privileges. Review reusable CI like application code and scope the runner/secret reach of consumers independently.

10. Worked scenario: twenty services need the same test baseline

The organization owns one GitLab group and wants a standard test image, lint job, and report artifact. Today the baseline changes monthly and must be reviewable per service.

Evidence: each service records the template project path, full SHA, expanded job, source SHA, and resulting report artifact. Upgrades happen by changing the pinned SHA in a reviewed merge request.

11. Tier/offering and portability

The core include/extends/anchor/reference mechanisms used here are available across GitLab offerings. Specific templates/components/inputs or newer include subkeys can be version-sensitive. A portable template should document its minimum GitLab version and avoid relying silently on administrator settings such as increased include limits.

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.