Parent-Child Pipelines, Dynamic Child Pipelines, Generated Configuration, and Monorepo Decomposition: Guided Hands-On Workflow and Core Operations

1. Guided scenario: a two-area disposable monorepo

Create a throwaway project with two synthetic areas: services/api/ and services/web/. Each area has a text file and its own child pipeline. Nothing deploys, publishes packages, touches cloud infrastructure, or requires privileged runners.

.
├── .gitlab-ci.yml
├── ci/
│   ├── children/
│   │   ├── api.yml
│   │   └── web.yml
│   └── generate_child.py
├── services/
│   ├── api/app.txt
│   └── web/app.txt
└── generated/

2. Preflight and assumptions

• Use a disposable GitLab project you are authorized to modify.
• Use GitLab Free-compatible parent-child pipelines. No catalog, protected environment, cloud, Kubernetes, or admin control is required.
• A normal non-privileged runner is sufficient for jobs that execute scripts. Trigger jobs themselves do not use runners.
• Record the GitLab offering/version visible to you and the Runner version/executor if runtime jobs execute.
• Do not create or print secrets. All variables in this lab are synthetic identifiers.

3. Static child A: API

stages: [verify]

api-verify:
  stage: verify
  image: alpine:3.20.3
  rules:
    - if: '$CI_PIPELINE_SOURCE == "parent_pipeline"'
  script:
    - test -f services/api/app.txt
    - mkdir -p evidence
    - printf 'area=api\nsha=%s\nchild_pipeline=%s\nsource=%s\n'         "$CI_COMMIT_SHA" "$CI_PIPELINE_ID" "$CI_PIPELINE_SOURCE" > evidence/api.txt
  artifacts:
    expire_in: 1 day
    paths: [evidence/api.txt]

4. Static child B: web

stages: [verify]

web-verify:
  stage: verify
  image: alpine:3.20.3
  rules:
    - if: '$CI_PIPELINE_SOURCE == "parent_pipeline"'
  script:
    - test -f services/web/app.txt
    - mkdir -p evidence
    - printf 'area=web\nsha=%s\nchild_pipeline=%s\nsource=%s\n'         "$CI_COMMIT_SHA" "$CI_PIPELINE_ID" "$CI_PIPELINE_SOURCE" > evidence/web.txt
  artifacts:
    expire_in: 1 day
    paths: [evidence/web.txt]

5. Parent pipeline: trigger only changed subtrees

stages: [children]

api-child:
  stage: children
  rules:
    - changes:
        - services/api/**/*
  variables:
    PARENT_PIPELINE_ID: "$CI_PIPELINE_ID"
    MONOREPO_AREA: "api"
  trigger:
    include:
      - local: ci/children/api.yml
    strategy: mirror

web-child:
  stage: children
  rules:
    - changes:
        - services/web/**/*
  variables:
    PARENT_PIPELINE_ID: "$CI_PIPELINE_ID"
    MONOREPO_AREA: "web"
  trigger:
    include:
      - local: ci/children/web.yml
    strategy: mirror

Make an API-only change. Prediction: the parent contains the API trigger but omits the web trigger; the created child has the same SHA as the parent and its jobs report parent_pipeline. Preserve the graph and IDs before changing the project again.

6. Evidence after the static run

7. Add a bounded generator instead of templating raw user input

The generator accepts exactly one area from a hard-coded allowlist and emits a fixed job shape. It does not accept raw YAML, shell fragments, image names, includes, or arbitrary job counts.

from pathlib import Path
import os, sys

allowed = {"api", "web"}
area = os.environ.get("AREA", "")
if area not in allowed:
    raise SystemExit(f"AREA must be one of {sorted(allowed)}")

job = f"""{area}-generated-verify:
  image: alpine:3.20.3
  script:
    - test -f services/{area}/app.txt
    - mkdir -p evidence
    - printf 'area={area}\\nsha=%s\\nchild_pipeline=%s\\nsource=%s\\n' "$CI_COMMIT_SHA" "$CI_PIPELINE_ID" "$CI_PIPELINE_SOURCE" > evidence/{area}-generated.txt
  artifacts:
    expire_in: 1 day
    paths:
      - evidence/{area}-generated.txt
"""
Path("generated").mkdir(exist_ok=True)
Path("generated/child.yml").write_text(job, encoding="utf-8")

8. Generate, inspect, then trigger the dynamic child

stages: [generate, children]

generate-api-child:
  stage: generate
  image: python:3.13.7-alpine3.22
  variables:
    AREA: "api"
  script:
    - python ci/generate_child.py
    - test "$(grep -c '^[a-z].*-generated-verify:' generated/child.yml)" -eq 1
    - sed -n '1,120p' generated/child.yml
  artifacts:
    name: "generated-child-$CI_PIPELINE_ID-$CI_JOB_ID"
    expire_in: 1 day
    paths:
      - generated/child.yml

run-generated-api:
  stage: children
  trigger:
    include:
      - artifact: generated/child.yml
        job: generate-api-child
    strategy: mirror

The printed YAML contains no secret. In a production generator, prefer a dedicated validation step and preserve a digest of the generated artifact. The trigger artifact path uses GitLab server path syntax; do not assume the runner operating system controls this path.

9. Dynamic configuration constraints to observe

• The generated artifact must fit instance artifact/configuration limits.
• The dynamic child’s include section cannot interpolate CI/CD variables.
• The generator job runs on a runner; the trigger job does not run a script.
• Generated configuration is compiled after the generator succeeds, so syntax or semantic errors are child-creation failures, not generator-runtime success.
• Keep generation deterministic for the same validated metadata and source SHA.

10. Challenge: which layer should solve each requirement?

11. Cleanup

Export only the evidence you need, then delete the disposable branch/project resources you created. Do not delete unrelated pipelines or artifacts by ambiguous “latest” selection. If the project is shared, remove only the lab files/branch after confirming the exact ref.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-11. Parent/child pipeline syntax, downstream status behavior, report visibility, hierarchy limits, inputs, and variable forwarding are version-sensitive. Re-check the deployed GitLab version before relying on newer syntax such as strategy: mirror.

• Downstream pipelines — parent-child semantics, dynamic child pipelines, nesting, pipeline source, reports, variables, inputs, and status behavior.
• CI/CD YAML syntax reference — trigger, trigger:include, trigger:strategy, trigger:forward, and needs:pipeline:job.
• Use CI/CD configuration from other files — include rules and dynamic-child configuration limitations.
• Troubleshooting downstream pipelines — empty child pipelines, permission/configuration failures, and variable forwarding issues.
• CI/CD limits — downstream hierarchy sizing and resource-protection rationale.
• Pipelines API — listing pipelines and querying child pipelines with source=parent_pipeline.