pipeline-generator

A CLI tool that runs inside GitLab CI to generate child pipelines for workspace monorepos (pnpm, npm, or yarn). It reads the dependency graph and emits a pipeline where each package's jobs use GitLab-native rules:changes with compare_to to skip unchanged packages.

How it works

1. A parent pipeline runs the generator
2. The generator resolves the last successful sentinel commit via the GitLab API
3. It reads the workspace graph and per-package CI configs
4. It emits a fully resolved child-pipeline.yml with dependency-aware needs and change-based rules
5. GitLab triggers the child pipeline

Installation

pnpm add -D gitlab-monorepo

Usage

Add a .pipeline-generator.yml to your repo root. The package manager is auto-detected from your lockfile:

tasks:
  build:
    dependsOn: ["^build"]
  test:
    dependsOn: ["build"]
  lint: {}

Preset defaults for image, before_script, and cache are provided based on the detected package manager. Override any of them via jobDefaults:

jobDefaults:
  image: node:22
  tags:
    - docker

Add a .gitlab-ci.yml:

generate-pipeline:
  image: node:20
  script:
    - corepack enable
    - pnpm install --frozen-lockfile
    - pnpm generate-pipeline
  artifacts:
    paths:
      - child-pipeline.yml

trigger-pipeline:
  needs: ["generate-pipeline"]
  trigger:
    strategy: depend
    include:
      - artifact: child-pipeline.yml
        job: generate-pipeline

Inspecting pipelines with glab

Use glab to inspect pipelines from the terminal.

List recent pipelines

glab ci list

State       IID   Ref     Created
(success) • #5    master  (about 10 minutes ago)
(failed)  • #4    master  (about 15 minutes ago)

Check current pipeline status

glab ci status

(success) • 00m 40s   prepare   generate-pipeline
https://gitlab.com/yourorg/yourrepo/-/pipelines/12345
Pipeline state: success

View job logs

glab ci trace generate-pipeline

Get pipeline details by ID

glab ci get -p 12345

View child pipeline jobs via API

The child pipeline is triggered via a bridge job. To see its jobs:

# Get the child pipeline ID from the bridge
glab api projects/<project-id>/pipelines/<parent-id>/bridges \
  | jq '.[].downstream_pipeline.id'

# List jobs in the child pipeline
glab api projects/<project-id>/pipelines/<child-id>/jobs \
  | jq '.[] | {name, status}'

Example output:

{"name": "core:build",        "status": "success"}
{"name": "core:test",         "status": "success"}
{"name": "utils:build",       "status": "success"}
{"name": "api:build",         "status": "success"}
{"name": "api:test",          "status": "success"}
{"name": "pipeline-success",  "status": "success"}
{"name": "api:deploy",        "status": "manual"}

View a specific job's log

glab api projects/<project-id>/jobs/<job-id>/trace

Create and watch an MR pipeline

# Push a branch and create MR
git push origin my-feature
glab mr create --title "My feature" --target-branch main

# Watch the pipeline
glab ci status

# List pipelines for the branch
glab ci list --branch my-feature

Example

See gitlab-monorepo-pipelines-example for a complete working example.

Documentation

See pipeline-generator-spec.md for the full specification.