Monorepo CI that checks affected applications
Affected CI should select applications through their dependency graph, not just their directory names. Treat shared configuration and uncertain change detection conservatively, then expose one stable required gate that verifies every selected check completed successfully.
Inside this article 6 sections +
Selective CI is useful only if it selects every application whose behavior could change. A directory filter can notice edits under an app, but miss a shared authentication package, root TypeScript configuration, or lockfile update that affects several apps. The selection algorithm is therefore part of the repository's correctness boundary.
Consider a monorepo with a customer portal, an operations console, and a background worker. The portal and console share interface components; all three share account authorization. A change in authorization should test all three even when no application directory changed.
Represent dependencies explicitly
Build or obtain a graph that maps applications to the packages and configuration they consume. Use the package manager and build system's dependency information where possible, then add implicit dependencies that import analysis cannot discover. Code generation inputs, shared test fixtures, container bases, and deployment templates can affect behavior without appearing as ordinary imports.
- Account authorization
- Portal, operations console, and worker must be checked.
- Shared UI components
- Portal and operations console must be checked.
- Worker processor
- Worker checks run, plus any declared integration contract consumers.
- Root toolchain or lockfile
- Run the documented broad check set unless a tested narrower rule exists.
Keep the graph under review as architecture changes. A newly added runtime plugin or generated client can create a dependency the current selector does not know about. Require the same change to update selection fixtures so the optimization stays aligned with the application model.
Choose the comparison revisions deliberately
A pull-request check needs a meaningful base and head for the proposed change. A push build may need a different comparison, and a merge queue checks a synthesized combination of changes. Do not assume the previous commit is always the correct base or that a shallow checkout contains the required history.
Record the compared revisions in the workflow summary. If the base cannot be resolved, fail the selector or run the conservative full set. Returning an empty affected list because a Git command failed turns missing evidence into permission to merge.
Handle deleted and renamed files. Removing a shared package can affect consumers even when the package no longer exists in the head graph. Compare relevant dependency information from both sides or use a tool that explicitly handles this case. A deletion should not disappear merely because the selector scans only current directories.
Test the selector as application logic
Create fixtures for an app-only change, a shared-package change, root configuration, dependency lockfile, generated schema, deleted package, and documentation-only change. State the expected application set for each fixture. The goal is not to assert the implementation's current output; it is to encode the repository's intended impact rules.
Illustrative selection policy:
changed files -> owning packages and implicit inputs
owning packages -> transitive dependent applications
unknown ownership or unavailable comparison -> full check set
empty legitimate application set -> explicit no-work result
selected applications -> bounded test/build matrix
Keep unknown files visible. A new root file should not default to harmless merely because it is absent from an allowlist. Either classify it deliberately or use a conservative fallback. Review false positives after correctness is established; a slightly broader build is preferable to an unexplained missed consumer.
Separate build dependencies from integration dependencies. The worker may not import the portal's API client, yet a changed API schema can affect both. Contract fixtures can add the required cross-application checks without forcing every source edit to rebuild the entire repository.
Expose one stable required gate
GitHub workflow-level path filtering can leave a required check pending when the workflow never runs. A more predictable design starts the selection workflow for relevant repository events and finishes with a stable aggregate job. That job reports success only when selection succeeded and every required selected check produced an acceptable result.
The aggregate must run even when an upstream job fails or is skipped, then inspect those outcomes explicitly. Do not make it always succeed simply to avoid pending checks. Distinguish a deliberate empty matrix from a canceled build, failed selector, missing report, or unexpectedly skipped test.
Give the gate a stable name that branch protections and rulesets can require. Dynamic matrix names are useful for diagnostics but can be awkward as the sole merge contract. If the repository uses a merge queue, ensure the workflow also handles its required event context and comparison semantics.
Keep optimization separate from evidence
Build caches can reduce repeated work, but their keys must include the inputs that determine validity. An affected selector deciding that an app needs checking should not be bypassed by an unrelated cache hit. Record whether the result came from a validated build cache and which source inputs its key represents.
Bound matrix concurrency to the runner and dependency budget. Ten integration tests sharing a small database can become slower and less reliable than a smaller parallel set. Isolate fixtures by run and application so one canceled matrix job does not delete another job's resources.
Cancel obsolete pull-request runs when appropriate, while preserving required evidence for the current revision. A completed result for an earlier head must not satisfy the current change accidentally. Deployment serialization has different needs from PR cancellation and should use a separately reviewed policy.
Compare selective and full runs before relying on selection
Initially compute the affected set while continuing the existing full checks. Compare whether failures occur outside the selected applications and investigate missing dependencies. Once the selector is credible, use periodic full checks to detect graph drift and unexpected toolchain coupling.
The module boundary guide helps make dependencies explicit, and delivery acceptance defines the evidence needed to merge. Repository and application implementation should optimize feedback time while preserving a clear explanation of what was verified.