Orbit has grown. The API, the web front end and the infrastructure live in separate repositories, the main .gitlab-ci.yml is 400 lines, and three other teams copied it and now maintain three slightly different versions. This lesson covers the tools GitLab gives you to split, share and connect pipelines, from a simple include to versioned components and pipelines that trigger other pipelines.
include: split one file into many
include pulls YAML from other files and merges it into the pipeline before it runs:
include:
- local: ci/build.yml # a file in this repository
- local: ci/deploy.yml
- project: orbit-team/ci-templates # a file in another GitLab project
ref: v2.3.0
file: /templates/node.yml
- template: Jobs/SAST.gitlab-ci.yml # a template shipped with GitLab
- remote: https://example.com/ci/lint.yml # any HTTPS URL
| Type | Source | Pin it with |
|---|---|---|
local | Same repository and commit | Nothing needed, it moves with your code |
project | Another project on the same GitLab | ref: a tag or commit SHA |
template | GitLab’s built-in templates | Changes with your GitLab version |
remote | Any public URL | Nothing reliable; avoid for anything important |
component | The CI/CD Catalog or any project | @version |
Included content merges with your file. If both define the same job, your file’s keys win, which lets you tweak an included job without copying it:
include:
- project: orbit-team/ci-templates
ref: v2.3.0
file: /templates/node.yml
unit-tests: # defined in node.yml, extended here
variables:
NODE_OPTIONS: --max-old-space-size=4096
include can also be conditional with rules, for example only including the deploy file on the default branch.
Pin shared includes. A project include without ref follows the default branch of the template project. Someone else’s merge can change your production pipeline without you noticing. Use tags.
CI/CD components
A component is a reusable, versioned piece of pipeline with a declared interface. Think of it as a function: it takes typed inputs and produces jobs.
Writing a component
Components live in a dedicated project, in a templates/ folder. Here is orbit-team/ci-components/templates/node-test.yml:
spec:
inputs:
stage:
default: test
node_version:
default: "24"
options: ["22", "24"]
coverage_threshold:
type: number
default: 70
run_lint:
type: boolean
default: true
---
"node-test":
stage: $[[ inputs.stage ]]
image: node:$[[ inputs.node_version ]]-alpine
script:
- npm ci
- npx c8 --check-coverage --lines $[[ inputs.coverage_threshold ]] node --test
"node-lint":
stage: $[[ inputs.stage ]]
image: node:$[[ inputs.node_version ]]-alpine
needs: []
variables:
RUN_LINT: "$[[ inputs.run_lint ]]"
script:
- npm ci
- npm run lint
rules:
- if: $RUN_LINT == "true"
The spec header, separated by ---, declares the inputs. The body uses them with $[[ inputs.name ]]. Inputs are checked when the pipeline is created: a wrong type or a value outside options fails immediately with a clear message, instead of a job breaking ten minutes later.
Using a component
include:
- component: $CI_SERVER_FQDN/orbit-team/ci-components/node-test@1.4.0
inputs:
node_version: "24"
coverage_threshold: 80
| Version reference | Resolves to |
|---|---|
@1.4.0 | Exactly that release (recommended) |
@~latest | The newest published release |
@main | The tip of a branch, for testing |
@3f9c2a1b… | A specific commit SHA |
Publishing to the CI/CD Catalog
Mark the component project as a CI/CD Catalog project in its settings, add a README, and release versions from a tag pipeline:
create-release:
stage: deploy
image: registry.gitlab.com/gitlab-org/cli:latest
script: echo "Releasing $CI_COMMIT_TAG"
release:
tag_name: $CI_COMMIT_TAG
description: "Release $CI_COMMIT_TAG"
rules:
- if: $CI_COMMIT_TAG =~ /^\d+\.\d+\.\d+$/
Released components appear in the CI/CD Catalog (Explore → CI/CD Catalog), where other teams can search and read them. Components use semantic versions, so consumers decide when to take breaking changes. GitLab 19 added component analytics so platform teams can see which projects run which versions.
spec:inputs outside components
Any included file, and even the main .gitlab-ci.yml, can declare spec:inputs. In the main file they become a typed form when someone runs the pipeline manually, a stricter replacement for the variables with options you saw in lesson 4.
Parent-child pipelines
Inside one repository, a big pipeline can be split into child pipelines. The parent triggers them like jobs; each child has its own stages, its own graph and its own status.
Orbit’s monorepo runs the API and web pipelines only when their folder changed:
# .gitlab-ci.yml (parent)
stages: [triggers]
api:
stage: triggers
trigger:
include: api/.gitlab-ci.yml
strategy: depend
rules:
- changes: [api/**/*]
web:
stage: triggers
trigger:
include: web/.gitlab-ci.yml
strategy: depend
rules:
- changes: [web/**/*]
strategy: depend makes the trigger job wait for the child and copy its status. Without it, the trigger job passes as soon as the child is created, and a failing child would not fail the parent. Use depend almost always.
Dynamic child pipelines
A job can generate a pipeline file and a trigger job can run it. This is how teams build one job per service in a monorepo without listing them by hand:
generate-pipeline:
stage: build
image: alpine:3
script:
- ./ci/generate.sh > generated.yml
artifacts:
paths: [generated.yml]
run-generated:
stage: test
needs: [generate-pipeline]
trigger:
include:
- artifact: generated.yml
job: generate-pipeline
strategy: depend
generate.sh can inspect which services changed and write a job for each. Keep generators simple and print the generated YAML in the log so people can debug it.
Multi-project pipelines
When work spans repositories, a job can trigger a pipeline in another project. Orbit’s API pipeline, after deploying to staging, starts the end-to-end suite that lives in orbit-team/e2e:
trigger-e2e:
stage: verify
needs: [deploy-api-staging]
variables:
TARGET_URL: https://staging.orbit.example.com
API_VERSION: $CI_COMMIT_SHORT_SHA
trigger:
project: orbit-team/e2e
branch: main
strategy: depend
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variableson a trigger job are passed to the downstream pipeline, with high precedence there.- The user who runs the upstream pipeline needs permission to run pipelines in the downstream project.
- The pipeline graph shows the downstream pipeline as a linked card; click it to follow.
Passing data back and forth
| Need | Use |
|---|---|
| Pass a few values downstream | variables on the trigger job |
| Pass a dynamic value computed upstream | A dotenv report in an upstream job, then needs it from the trigger job |
| Download artifacts from another project’s job | needs:project (Premium) |
| Download artifacts from a child pipeline | needs:pipeline:job in the parent |
| Call the API without a personal token | CI_JOB_TOKEN, allowed in the target project’s job token allowlist |
use-shared-schema:
needs:
- project: orbit-team/api-schema
job: build-schema
ref: main
artifacts: true
script:
- ls schema/
Triggering from outside GitLab
Other systems start pipelines through the API with a pipeline trigger token (created under Settings → CI/CD → Pipeline trigger tokens):
$ curl --fail --request POST \
--form "token=$TRIGGER_TOKEN" \
--form "ref=main" \
--form "variables[TARGET_URL]=https://staging.orbit.example.com" \
"https://gitlab.com/api/v4/projects/12345/trigger/pipeline"
Inside GitLab CI, prefer the trigger keyword: it needs no token and links the pipelines in the UI.
Choosing the right tool
| Situation | Tool |
|---|---|
| One repository, long file | include: local |
| Same jobs in many repositories | CI/CD component (or a pinned project include) |
| Monorepo, independent parts | Parent-child pipelines with rules:changes |
| Unknown number of jobs until runtime | Dynamic child pipeline |
| Work continues in another repository | Multi-project trigger |
| External system starts a pipeline | Pipeline trigger token and the API |
Exercise
A parent pipeline triggers a child with trigger:include but without strategy: depend. The child fails. What does the parent show?
Show answer
Answer: A. Without strategy: depend, the trigger job succeeds once the downstream pipeline is created. With depend, it waits and mirrors the downstream result, which is almost always what you want.
Exercise
Three teams copied the same 200 lines of Node.js test jobs into their pipelines. What is the most maintainable fix?
Show answer
Answer: C. A component gives one source of truth, typed inputs for the parts that differ and semantic versions so each team upgrades on purpose. Anchors only work inside one file and unpinned remote includes can change under you.
Key takeaways
includemerges YAML from local files, other projects, GitLab templates and components; pin anything you do not own.- Components are versioned pipeline building blocks with typed
spec:inputs, shared through the CI/CD Catalog. - Parent-child pipelines split one repository’s work; dynamic children generate jobs at runtime.
- Multi-project triggers connect repositories;
strategy: dependmakes the upstream wait and reflect the result. - Pass data with trigger variables, dotenv reports,
needs:projectand the job token.
FAQ
What is the difference between a template include and a component?
Templates are plain YAML you include and override; there is no declared interface or versioning beyond your GitLab version. Components declare typed inputs, are released with semantic versions and are discoverable in the Catalog. For anything shared across teams, prefer components.
How deep can child pipelines nest?
Child pipelines can trigger their own children, up to a depth limit set by GitLab (a few levels). If you need more than two levels, the design is usually too complicated.
Can a downstream pipeline see the upstream’s protected variables?
No. Variables are passed explicitly through the trigger job, and the downstream project’s own protected variables follow its own branch protection. This keeps the boundaries between projects clear.
How do I test a change to a component before releasing it?
Include it with @your-branch or a commit SHA in a test project, and add a test pipeline in the component project itself that includes the component from the current commit with $CI_COMMIT_SHA.
Why does my multi-project trigger fail with a permission error?
The user who ran the upstream pipeline must be able to run pipelines on the target branch of the downstream project. If that branch is protected, they also need permission to merge into it.