GitLab Monorepo CI/CD Pipeline Guide: Run Jobs Only When Folders Change

GitLab Monorepo CI/CD Pipeline Guide#

Learn how to design GitLab CI/CD pipelines for monorepos using folder-based rules, changed-file detection, child pipelines, shared templates, cache, artifacts, and deployment controls.

Quick answer#

Use path rules#

Run frontend jobs only when frontend files change, backend jobs only when backend files change.

Use shared templates#

Keep common logic in reusable includes to avoid repeating YAML.

Use child pipelines#

For large monorepos, split pipelines by app or service.

Sample monorepo structure#

monorepo/ apps/ frontend/ api/ services/ worker/ infra/ terraform/ .gitlab-ci.yml

Run jobs only when paths change#

frontend_tests: stage: test script: - cd apps/frontend - npm ci - npm test rules: - changes: - apps/frontend/**/* api_tests: stage: test script: - cd apps/api - pip install -r requirements.txt - pytest rules: - changes: - apps/api/**/*

Use workflow rules#

Workflow rules help control whether a pipeline should be created at all.

workflow: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_COMMIT_BRANCH == "main"' - when: never

Use child pipelines for larger monorepos#

When a monorepo grows, a single giant YAML file becomes hard to maintain. Child pipelines help split responsibilities by folder or service.

frontend_pipeline: trigger: include: apps/frontend/.gitlab-ci.yml rules: - changes: - apps/frontend/**/*

Cache and artifacts in monorepos#

Deployment strategy#

• Deploy only the affected app or service.
• Use environment names like frontend/staging and api/production .
• Use manual production deployments.
• Use protected variables for production credentials.

Common mistakes#

• Running every job for every small change.
• Using one cache key for the entire monorepo.
• Ignoring shared library dependencies.
• Keeping all YAML in one huge file.
• Deploying all services when only one changed.

Best practices#

• Use rules:changes for folder-aware pipelines.
• Use child pipelines for large repositories.
• Use clear app/service ownership.
• Document folder-level pipeline behavior.
• Keep shared templates versioned and reviewed.

• GitLab CI/CD Learning Path
• GitLab Rules and Workflow
• Python, Angular and Django Pipeline Examples

Official references#

• GitLab rules:changes documentation
• GitLab downstream and child pipelines