When would you split a GitLab CI configuration into parent and child pipelines with `trigger:include`, and what do you give up by doing it?

## What the mechanism is A normal job runs a script on a runner. A **trigger job** does not: it tells GitLab to create another pipeline. Two forms matter here: ```yaml # child pipeline, same project backend: stage: build trigger: include: backend/.gitlab-ci.yml strategy: depend # multi-project pipeline downstream: stage: deploy trigger: project: platform/deployer branch: main strategy: depend ``` A child pipeline is a separate pipeline object with its own stages, its own job graph, and `$CI_PIPELINE_SOURCE == "parent_pipeline"`. It appears in the parent's graph as an expandable node, not as jobs inside the parent. The **dynamic** variant is what makes the feature powerful: one job writes YAML — from a component inventory, a template, whatever the repository knows at that moment — publishes it as an artifact, and the trigger job includes it from that artifact. ```yaml generate: stage: build script: ./scripts/generate-pipeline.sh > generated.yml artifacts: paths: [generated.yml] run-generated: stage: test trigger: include: - artifact: generated.yml job: generate strategy: depend ``` This is the only sanctioned way to decide the *set of jobs* from information computed during the run, because ordinary `rules:` are evaluated before anything executes. ## The two cases that justify the split **Genuine dynamism.** The job set depends on something the pipeline discovers — which components exist, what a manifest declares, how many shards a test suite needs. No amount of static configuration expresses that. **Comprehension and blast radius.** A configuration that no single person can hold in their head is a delivery risk regardless of how it is factored. Splitting along ownership boundaries lets a team change its own child pipeline without reviewing everyone else's rules, and confines a mistake to one child. Pipeline creation itself also gets cheaper: a child that is never triggered costs nothing to evaluate. Neither case is "the file is long". Length alone is usually a factoring problem inside one pipeline, not a reason for a second one. ## What you give up **Status propagation is opt-in.** Without `strategy: depend`, the trigger job goes green the moment the downstream pipeline is *created*. The parent can report success over a failed child. `strategy: depend` makes the trigger job mirror the downstream pipeline's status and wait for it. Forgetting it is the single most common parent-child bug. **Ordering does not cross the boundary.** `needs:` links jobs within one pipeline. There is no way to say "this child job runs after that parent job" beyond the trigger point itself. The cross-pipeline forms — `needs:pipeline:job` for a parent or upstream pipeline, `needs:project` for another project — download artifacts; they are not scheduling edges. Any sequencing you need must be expressed as trigger points, which is coarser. **Context must be forwarded.** A child does not automatically inherit everything. Variables defined on the trigger job pass down, and `trigger:forward` controls whether pipeline variables and YAML-defined variables are forwarded. Getting this wrong produces a child that runs with a subtly different environment from the parent — the hardest class of pipeline bug to see. **Observability fragments.** One pipeline is one page. A parent with six children is seven pages, seven durations, and a merge request widget that shows the parent's status. Nested children add another level, and GitLab limits how deep nesting may go. **Generated YAML is harder to review.** With a dynamic child, the artifact — not the repository — is the source of truth for what ran. Code review sees the generator, not its output. Teams that do this well publish the generated file as an artifact and lint it in the generating job, so at least the run is auditable after the fact. ## How to decide Ask three questions in order. Is the job set knowable before the pipeline starts? If yes, static configuration wins and there is nothing to discuss. If no, a dynamic child is the only mechanism that fits. If it is knowable but the configuration is unmanageable, ask whether the real problem is ownership — several teams editing one file — or just structure. Ownership is a legitimate reason to split into children along team lines; structure is better solved inside one pipeline. Then ask what the failure story looks like. If a broken child must fail the merge request, `strategy: depend` is mandatory and you should say so out loud. If a downstream deployment pipeline in another project should *not* block this one, the absence of `strategy: depend` is a deliberate choice, not an oversight — and it should be commented as such. ## The migration cost nobody budgets Splitting an established pipeline is not a refactor you finish in an afternoon. Every rule that referenced a job by name across the new boundary breaks, artifact paths change hands, and the team's mental model of "where do I look when it is red" has to be rebuilt. Do it when the current shape is actively costing delivery time, and do it along a boundary — ownership or generated-versus-static — that will still make sense in a year.