5. Reusable pipelines: include, extends, anchors, children¶
Why this matters¶
One 500-line .gitlab-ci.yml is unmaintainable; every org eventually splits
and reuses pipeline config. GitLab gives you four reuse mechanisms that
solve different problems — picking the wrong one is a classic interview
stumper and a real maintenance smell.
The four mechanisms (decision table)¶
| Mechanism | Scope | Solves |
|---|---|---|
include: |
file-level | split config into modules; share org templates |
extends: |
job-level | inherit and override a template job |
YAML anchors &/*/<<: |
within one file | dedupe repeated blocks (used by .deploy-base) |
trigger: child pipeline |
pipeline-level | monorepo: run only the sub-pipeline that changed |
This repo's split¶
# .gitlab-ci.yml
include:
- local: '.gitlab/ci/test.yml'
- local: '.gitlab/ci/build-kaniko.yml'
- local: '.gitlab/ci/package-chart.yml'
- local: '.gitlab/ci/deploy.yml'
Each stage file is independently readable and the root file stays a table
of contents. include: variants to know: local (this repo), project
(another repo + ref), remote (URL), template (GitLab-built security
templates — Phase 2 uses them), component (CI/CD catalog, with typed
inputs:).
extends vs anchors¶
Both dedupe job definitions; differ subtly:
.job-template: # hidden job (leading dot) = template
image: alpine/k8s:1.31.2
before_script: [setup-kubeconfig.sh]
deploy:dev:
extends: .job-template # merges + overrides; crosses include boundaries
.deploy-base: &deploy-base # anchor on a hidden job
stage: deploy
deploy:prod:
<<: *deploy-base # pure YAML merge — same file only
Use extends for cross-file templates; anchors for same-file
shorthand. (!reference lets a script line be borrowed selectively.)
Child pipelines¶
trigger-sub:
trigger:
include: backend/.gitlab-ci.yml # runs as a downstream pipeline
strategy: depend # parent waits for child result
rules:
- changes: [backend/**/*]
Monorepo pattern: parent pipeline fans out to per-service child pipelines
scoped by changes: — each child reports status upstream with
strategy: depend.
Hands-on¶
- Refactor drill: inline all four
.gitlab/ci/*.ymlinto one file, lint it, then re-split. The include version is what you'd actually maintain. - Convert
.deploy-basefrom anchor toextends:— verifyglab ci lintand the rendered job list are unchanged. - Add a
project:include pointing at a second repo you own with a shareddocker-build.ymltemplate — the beginning of an org template library.
Deliberate break & triage¶
- Break 1: include
deploy.ymltwice →glab ci lintflags duplicate job names (second include silently wins in some versions — worse!). - Break 2: a job in
test.ymlextends:a.templatedefined only indeploy.yml, buttest.ymldoesn't include it → template not found.extendsresolves post-include-merge, but readability suffers — keep templates near consumers or in a shared include. - Break 3: anchor
when: manualonto the same job asrules:→ lint error "when may not be used with rules". They are mutually exclusive job keys.
Verify¶
- You can name when each of the 4 mechanisms is correct
- The pipeline lints with includes split or inlined
- You can draw where artifacts/variables flow between parent and child