zero gravitySOLUTIONS
← All insightsCI/CD & DELIVERY / DEPENDENCY-AWARE CI DESIGN

Monorepo CI that checks affected applications

QUICK ANSWER

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.

ILLUSTRATIVE MONOREPO CHANGE MAP
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.
Selection follows downstream dependency impact. Folder ownership alone cannot establish which applications are unaffected.

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.

FROM INSIGHT TO ACTIONCustom software development

Make selective CI trustworthy.

We can implement dependency-aware checks, conservative fallback behavior, and a stable gate for your repository.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.