.gitlab-ci.yml Structure, Pipeline Compilation, Keywords, Defaults, and Configuration Validation: Configuration, Design Choices, and Tradeoffs

1. Defaults versus explicit job configuration

Defaults reduce repetition when many jobs genuinely share one policy. They become harmful when a reader must mentally reconstruct many exceptions to understand a safety-critical job. A deployment job, privileged image-build job, or compliance job often benefits from more explicit configuration even when ordinary test jobs share defaults.

2. Know the default copy boundary

A subtle but important rule: default keyword values are copied into a job only when that job has not defined the same keyword. They are not recursively merged with job-defined values. Therefore “put half the artifacts policy in default and half in the job” is not a safe mental model.

default:
  retry: 2
  interruptible: true

fast_test:
  retry: 0       # this job uses 0, not a merge with default retry
  script:
    - echo test

When reviewing a job, reason from the compiled job, not from “the defaults plus whatever seems missing.”

3. Explicit configuration versus inheritance

Inheritance trades local readability for centralized policy. The right balance depends on change frequency and consequence. A shared before_script that installs harmless test tooling may be fine as a default. A hidden inherited command that changes cloud authentication or deployment targets is much harder to review safely.

4. Local simplicity versus reusable includes

An include changes the configuration trust graph. Local includes stay inside the same project/revision. Project includes cross a repository boundary and should use deliberate, reviewable refs. Remote includes cross into a URL trust boundary. CI/CD components add a versioned interface model and are covered deeply later in the course.

5. Merge order is part of the design

GitLab resolves nested includes recursively, merges included files in order, then merges the main configuration last. Main-file values can therefore override included configuration. Hash mappings can deep-merge; array-like/non-map values are replaced rather than appended item-by-item. This makes “override one command in a script array” a common source of surprises.

# included.yml
test:
  script:
    - install_dependencies
    - run_tests

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

test:
  script:
    - echo "replacement script"   # replaces the included script list

If you intend to retain the included commands, reproduce them or choose a different reuse mechanism. Verify in Full configuration instead of assuming list concatenation.

6. Static validation versus simulation versus execution

Use the cheapest evidence layer that can answer the current question, then move one layer deeper only when needed. This reduces feedback time and prevents unnecessary side effects during diagnosis.

7. Pipeline snapshots improve reproducibility—but new pipelines can differ

When GitLab creates a pipeline, included configuration is evaluated and stored as part of that pipeline’s configuration snapshot. A job rerun stays on that snapshot. A new pipeline resolves includes again. If an external include is mutable, two pipelines for the same application source can compile differently at different times.

8. Worked scenario: central test policy without hiding deployment behavior

A platform team wants common retry/interruption behavior for 40 service repositories, but each service owns its production deployment command. A reasonable design is to centralize low-risk test defaults in a versioned project include/component while keeping production deployment job configuration explicit in each service or a separately governed deployment component.

9. Design anti-patterns

• Inheritance as obscurity: a job’s behavior requires opening many files and guessing merge order.
• One giant root file: avoiding every include even when stable domain boundaries are obvious.
• Mutable central config: consuming main from a shared project as if it were an immutable release.
• Lint-only confidence: treating static validation as proof that source-specific rules or runtime commands work.
• Copy-paste forks: duplicating a shared policy into dozens of projects until fixes cannot propagate consistently.

10. Review checklist for a maintainable configuration

• Can a reviewer identify the root file and every include without privileged access?
• Are shared configurations pinned/versioned according to their trust level?
• Can Full configuration explain the final job without guesswork?
• Are inherit exceptions intentional and documented?
• Are deprecated patterns being introduced, or only maintained temporarily for migration?
• Is simulation used when pipeline source/rules affect whether jobs exist?
• Are runtime side effects kept out of configuration-validation exercises?

Knowledge check

Official references and version notes

• CI/CD YAML syntax reference — current global/job keyword semantics, including default, inherit, and include.
• Use CI/CD configuration from other files — include resolution, merge order, overrides, nesting, and snapshot behavior.
• Validate GitLab CI/CD configuration — CI Lint, syntax checking, and pipeline simulation.
• Pipeline editor — included-file tree, visualization, continuous validation, and Full configuration.
• Deprecated CI/CD keywords — current migration guidance, including global image/services/cache/before_script/after_script and legacy only/except.
• glab ci lint and glab ci config — current CLI surfaces for validation and compiled configuration inspection.