.gitlab-ci.yml Structure, Pipeline Compilation, Keywords, Defaults, and Configuration Validation: Diagnostics, Failure Modes, Security, and Performance

1. Evidence-first diagnostic ladder

            flowchart TD
             A[Preserve source SHA + original error] --> B[Parse / GitLab lint]
             B --> C[Resolve includes]
             C --> D[Inspect merged defaults + inheritance]
             D --> E[Simulate pipeline creation]
             E --> F[Inspect final jobs]
             F --> G[Queue + runner eligibility]
             G --> H[Runtime script/tool/network]
             H --> I[Artifacts/deployment/external state]
          

This order minimizes false leads. A missing include can never be fixed by adding runner capacity. A when: never workflow does not become runnable because the shell executor is healthy. Conversely, once a job is running, reformatting YAML is unlikely to explain a command exit code unless the compiled job shows different commands than expected.

2. Failure case: bad YAML typing or structure

stages: verify      # wrong type: stages expects a list

verify:
  stage: verify
  script:
    - echo ok

Preserve the lint error text and the exact file revision. This is a pre-pipeline failure. There is no pipeline ID or runner log to inspect. Repair to:

stages:
  - verify

3. Failure case: supported today but deprecated configuration

# Legacy/deprecated global pattern
image: alpine:3.22
before_script:
  - echo preflight

verify:
  script:
    - echo verify

Current GitLab documentation deprecates globally defined image, services, cache, before_script, and after_script. The safer current pattern moves supported values under default. A deprecated construct is not the same as an immediate runtime failure; treat it as version/migration debt and preserve warnings.

default:
  image: alpine:3.22
  before_script:
    - echo preflight

4. Failure case: include resolution fails

include:
  - local: /.gitlab/ci/does-not-exist.yml

verify:
  script:
    - echo verify

CI Lint in project context must resolve local includes. If the file is missing at the relevant revision, configuration cannot compile. Check the exact path, case, repository revision, and include context before changing runner settings.

git ls-tree -r --name-only HEAD .gitlab/ci/
git show HEAD:.gitlab-ci.yml

5. Failure case: hidden inheritance changes runtime behavior

This failure is more subtle because the configuration can validate and a pipeline can run. The job silently opts out of a default bootstrap command:

default:
  before_script:
    - printf 'ready\n' > .chapter02-ready

verify:
  inherit:
    default: false
  script:
    - test -f .chapter02-ready

The job fails at runtime because the marker was never created. The first useful evidence is the compiled job: it shows inherit:default:false and no inherited before_script. Runner logs then confirm the expected consequence. Fix the configuration, not the runner.

6. Failure case: configuration is valid but no pipeline is created

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - when: never

verify:
  script:
    - echo verify

A push can produce no pipeline by design. Static lint success does not contradict that result. Inspect source context and simulate pipeline creation. The absence of a pipeline is evidence about workflow, not about runner availability.

7. Configuration dependencies are executable supply-chain dependencies

Remote/project includes can inject commands into jobs that later receive repository credentials, job tokens, protected variables, or deployment authority. Treat those includes like executable code dependencies. Review ownership, pin immutable refs where practical, use integrity/version controls where supported, minimize forwarded secrets, and keep privileged jobs isolated from untrusted configuration.

8. Configuration complexity can become a reliability/performance problem

GitLab documents a time limit for resolving all includes and a default cap on include count. Large nested graphs also impose human review cost even before platform limits are reached. Measure the actual need for abstraction: split by stable domain boundary, not simply because YAML can be split.

9. Failure taxonomy: preserve the boundary

10. Least-destructive repair procedure

1. Copy the original failing CI files and lint/simulation output into an evidence folder.
2. Record the exact source SHA and pipeline source/ref if a pipeline exists.
3. Inspect Full configuration / compiled YAML before editing.
4. Change the smallest configuration unit that explains the failure.
5. Re-run static lint first. If the failure involved pipeline creation, re-run simulation next.
6. Run a disposable pipeline only if runtime evidence is still required.
7. Compare the repaired evidence to the preserved first failure; do not simply declare “green.”

11. Intentionally broken diagnosis exercise

Given this pair of files, explain why verify fails and which artifact proves it:

# .gitlab/ci/base.yml
default:
  before_script:
    - printf 'prepared\n' > .prepared

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

verify:
  inherit:
    default: false
  script:
    - test -f .prepared

The configuration can compile. The expanded verify job demonstrates that before_script is absent. A runtime failure then confirms the causal consequence. The repair is either remove the opt-out or explicitly create the prerequisite in the job; changing runner permissions would be unrelated.

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.