Buildkite Monorepo Example

This repository demonstrates a Buildkite setup for managing multiple pipelines within a single monorepo using the monorepo-diff plugin.

👉 See these examples in action:

• Root pipeline - detects changes and triggers other pipelines
• Service App pipeline - runs service-app pipeline
• Test pipeline - runs test pipeline

See the full Getting Started Guide and How to set up Continuous Integration for a monorepo using Buildkite for step-by-step instructions on how to get this running.

Root pipeline: detects changed folders and triggers service/test pipelines

Service App pipeline: triggered by changes to service-app/

Test pipeline: triggered by changes to test/

How it works

This repository contains:

• A root pipeline (.buildkite/pipeline.yml) that uses the monorepo-diff plugin to detect changes and trigger sub-pipelines.
• A service-app folder with its own .buildkite/pipeline.yml
• A test folder with its own .buildkite/pipeline.yml

Each sub-pipeline is triggered when files within its folder change.

First time running this?

If you trigger a build without making changes to service-app/ or test/, you’ll see:

• A ✅ green build
• A message at the top of the build (in the Annotations tab) saying: “No changes detected - no pipelines triggered.”

This is expected! The root pipeline uses the monorepo-diff plugin to only trigger pipelines when changes are detected in watched folders.

💡 Tip: To test it out, try committing a small change inside service-app/ or test/.

Setup

To get started, fork this repository and create the pipelines using the buttons below.

You can watch any directory in your monorepo by specifying the watch attribute and its path in the root pipeline.

For a step-by-step walkthrough, see: How to set up Continuous Integration for a monorepo using Buildkite

Project Directories Structure (simplified)

.
├── .buildkite
│   ├── pipeline.yml            # Root pipeline: uses monorepo-diff
│   ├── scripts
│   │   └── git-diff-files.sh   # Diff script for detecting changes
├── service-app
│   ├── .buildkite
│   │   └── pipeline.yml        # service-app pipeline definition
└── test
    ├── .buildkite
    │   └── pipeline.yml        # test pipeline definition
├── README.md

Root Pipeline Example

The root pipeline uses the monorepo-diff plugin:

steps:
  - label: "Detect changed projects"
    plugins:
      - monorepo-diff#v1.3.0:
          diff: .buildkite/scripts/git-diff-files.sh
          watch:
            - path: "service-app"
              config:
                trigger: "monorepo-service-app-example"
            - path: "test"
              config:
                trigger: "monorepo-test-example"

Sub-Pipeline Setup

Each triggered pipeline (e.g. monorepo-service-app-example) should have a step like the following in its pipeline settings, so it knows which config file to load:

For the monorepo-service-app-example pipeline:

steps:
  - label: ":pipeline:"
    command: "buildkite-agent pipeline upload service-app/.buildkite/pipeline.yml"

For the monorepo-test-example pipeline:

steps:
  - label: ":pipeline:"
    command: "buildkite-agent pipeline upload test/.buildkite/pipeline.yml"

💡 You can configure this in the Buildkite UI under Pipeline Settings → Steps, or commit a .buildkite/pipeline.yml file directly in the appropriate folder and use it as the pipeline source.

⚠️ Avoid recursion!

Each pipeline points to the same repository. To avoid recursively loading the root pipeline again (which could cause infinite loops), each sub-pipeline should explicitly upload its own .buildkite/pipeline.yml using:

command: "buildkite-agent pipeline upload path/to/.buildkite/pipeline.yml"

GitHub Webhook Setup

Ensure GitHub webhooks or GitHub App integration is enabled for the repository:

• Go to Pipeline Settings → GitHub and follow the instructions.
• Enable Push and Pull Request events.

Create the Pipelines

1. Create the Root Pipeline

This pipeline uses the monorepo-diff plugin to detect changes and trigger the sub-pipelines.

📄 View the full root pipeline template.

2. Create the Service App Pipeline

This pipeline will run whenever changes are detected in the service-app/ folder.

📄 View the full service-app pipeline template.

3. Create the Test Pipeline

This pipeline will run whenever changes are detected in the test/ folder.

📄 View the full test pipeline template.

License

See LICENSE.md (MIT)