Skip to content
SiteSwarm Platform Documentation

Ci Change Detection

Monorepo CI Change Detection, Canary Scoping & Consolidated Gate

1. Executive Summary & Objectives

In a multi-tenant monorepo housing dozens of client applications (apps/*) and shared platform packages (packages/*), running full builds, typechecks, and browser evaluations across every application on every commit would exhaust CI runner minutes and slow down developer feedback loops.

SiteSwarm’s CI change-detection architecture enforces three principles:

  1. Path-Filtered Workspace Scoping: Every Pull Request evaluates modified file paths upfront (scripts/detect-changes.ts) to execute application builds and verification checks only for impacted workspaces.
  2. Canary Scoping for Shared Package Changes: When a shared package (packages/*) changes, Pull Request verification runs against representative canary applications rather than building and deploying every client application in the fleet on every commit.
  3. Single Consolidated Gate Status Check: Because matrix jobs expand or skip dynamically depending on which paths changed, a single terminal aggregator job named Gate evaluates all upstream job outcomes for branch protection enforcement.
flowchart LR
    PR["Pull Request Diff"] --> Detect["Evaluate Monorepo Changes\n(Path Filter & Dependency Graph)"]
    Detect -->|"Docs Only"| DocsFastPath["Docs & Link Linters Only"]
    Detect -->|"apps/<client>/*"| AppScoped["Target App Matrix\n(<client> Only)"]
    Detect -->|"packages/*"| CanaryScoped["Canary App Matrix\n(Representative Fleet Sample)"]
    DocsFastPath & AppScoped & CanaryScoped --> Gate["Consolidated 'Gate' Status Check"]

2. Change-Detection Tiers

  1. Documentation-Only Fast Path: Pull requests that modify only documentation or markdown files (docs/**, README.md, HIGH_LEVEL_DESIGN.md, AGENTS.md) skip application build and runtime matrices while still enforcing documentation taxonomy and relative link linters.
  2. Application-Scoped Matrix (apps/<client>/**): Changes confined to one or more client application directories trigger build, lint, and verification matrix jobs exclusively for those modified applications.
  3. Shared Package Canary Scoping (packages/**): When shared platform libraries or capabilities change, unit tests and typechecks run across the modified packages, and end-to-end application verification scopes to designated canary applications rather than the entire client fleet.

3. Why a Consolidated Gate Aggregator Job Is Required

GitHub’s branch rulesets require a fixed list of required status check names. If individual application matrix jobs (e.g., build (bakery), build (auto-repair)) were registered directly as required branch protection checks, any Pull Request that legitimately skipped an unmodified application would remain blocked forever waiting for that skipped check.

Instead, the CI workflow concludes with an if: always() aggregator job named Gate that inspects the result of every executed upstream job (failing if any required job failed or was cancelled, and succeeding when all executed jobs pass or are legitimately skipped). Branch protection rulesets then require Gate as the single authoritative CI status check.