Lesson 12 advanced

Includes, Components and Multi-Project Pipelines

Scale CI beyond one file: include local, project, remote and template files, build reusable CI/CD components with spec:inputs and publish them to the CI/CD Catalog, split work into parent-child and dynamic child pipelines, and connect repositories with multi-project triggers and cross-project artifacts.

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
TypeSourcePin it with
localSame repository and commitNothing needed, it moves with your code
projectAnother project on the same GitLabref: a tag or commit SHA
templateGitLab’s built-in templatesChanges with your GitLab version
remoteAny public URLNothing reliable; avoid for anything important
componentThe 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 referenceResolves to
@1.4.0Exactly that release (recommended)
@~latestThe newest published release
@mainThe 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
  • variables on 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

NeedUse
Pass a few values downstreamvariables on the trigger job
Pass a dynamic value computed upstreamA dotenv report in an upstream job, then needs it from the trigger job
Download artifacts from another project’s jobneeds:project (Premium)
Download artifacts from a child pipelineneeds:pipeline:job in the parent
Call the API without a personal tokenCI_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

SituationTool
One repository, long fileinclude: local
Same jobs in many repositoriesCI/CD component (or a pinned project include)
Monorepo, independent partsParent-child pipelines with rules:changes
Unknown number of jobs until runtimeDynamic child pipeline
Work continues in another repositoryMulti-project trigger
External system starts a pipelinePipeline 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?

  1. The trigger job passed, because it only waited for the child to be created
  2. The trigger job failed, matching the child
  3. The parent pipeline is cancelled
  4. The child is retried automatically
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?

  1. Keep the copies and review them every quarter
  2. Use YAML anchors in each repository
  3. Publish the jobs as a versioned CI/CD component with inputs and include it with a pinned version
  4. Use a remote include from a raw URL on the main branch
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

  • include merges 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: depend makes the upstream wait and reflect the result.
  • Pass data with trigger variables, dotenv reports, needs:project and 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.

↑ ↓ navigate Enter open Esc close