The Monorepo CI Trap: Why Your Runners Are Melting

Last Tuesday, a developer in my team pushed a 2-line change to a shared CSS utility library. Within seconds, GitHub Actions spawned 42 parallel build jobs, burning 340 minutes of runner time and blocking the entire engineering department's deployment queue for an hour. This is the 'Blast Radius' problem, and if your monorepo CI looks like a wall of red or a sea of unnecessary green, you are wasting money and slowing down your ship rate. In 2026, we shouldn't be building what hasn't changed. Period.

The landscape has shifted. We are no longer just dealing with a few packages in a packages/ folder. We are dealing with polyglot monorepos, micro-frontends, and serverless functions all living in one place. The standard on: push: paths: filter in GitHub Actions is a great start, but it fails the moment your dependency graph gets complex. If Package A depends on Package B, and you change Package B, Package A must be tested and rebuilt, even if its own files didn't change. Standard path filters don't know that. You need graph-aware pipelines.

Pattern 1: The Graph-Aware Dynamic Matrix

The most efficient way to handle a monorepo in GitHub Actions is to move away from static workflow files and toward dynamic job generation. Instead of hardcoding every service into your YAML, you should use a 'Discovery' job that calculates the affected graph and outputs a JSON matrix for subsequent jobs.

In 2026, we rely on tools like pnpm (v10.1+) or turborepo (v2.5+) to do the heavy lifting of graph analysis. The goal is to generate a list of only the packages that changed or whose dependencies changed.

The Discovery Script

Here is a concrete example of a discovery job using pnpm's advanced filtering. This script identifies changed packages between the current commit and the main branch, then formats them for a GitHub Actions matrix.

#!/usr/bin/env bash

.github/scripts/get-changed-packages.sh

Get the list of changed packages compared to origin/main

We use pnpm list with the --filter flag and --json output

CHANGED_JSON=$(pnpm list --filter="...[origin/main]" --depth=-1 --json)

Parse the JSON to extract names and paths into a compact array

echo $CHANGED_JSON | jq -c 'map({name: .name, path: .path})' > changed_packages.json

This script is the heart of your pipeline. By using ...[origin/main], pnpm looks at the diff between your branch and main, finds the changed files, maps them to packages, and then—crucially—includes all packages that depend on those changed packages.

Pattern 2: Implementing the Job Generator

Once you have the list of affected packages, you feed it into a GitHub Actions matrix. This allows you to scale horizontally. If 1 package changes, 1 job runs. If 50 packages change, GitHub spawns 50 parallel runners (up to your concurrency limit).

Example Workflow: Dynamic Orchestration

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  discover:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
      count: ${{ steps.set-matrix.outputs.count }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Important for diffing
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - name: Generate Matrix
        id: set-matrix
        run: |

      # Calculate affected packages
      LIST=$(pnpm list --filter="...[origin/main]" --depth=-1 --json)
      COUNT=$(echo $LIST | jq 'length')
      echo "matrix=$LIST" >> $GITHUB_OUTPUT
      echo "count=$COUNT" >> $GITHUB_OUTPUT

test: needs: discover if: ${{ needs.discover.outputs.count > 0 }} runs-on: ubuntu-latest strategy: fail-fast: false matrix: package: ${{ fromJson(needs.discover.outputs.matrix) }} steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 cache: 'pnpm' - name: Install dependencies run: pnpm install --frozen-lockfile - name: Test Package run: pnpm --filter ${{ matrix.package.name }} run test

This pattern solves the 'Opaque Pipeline' problem. Many teams simply run npx turbo run build in a single large GitHub Action job. While simple, it provides zero visibility into which specific package failed without digging through thousands of lines of logs. The dynamic matrix pattern gives you a separate UI element in GitHub for every affected package.

Pattern 3: Remote Caching and The 'Omit-on-Success' Strategy

Even with dynamic matrices, you will eventually hit the 256-job limit of GitHub Actions or simply run out of concurrency slots. This is where remote caching becomes mandatory. In 2026, we don't just cache node_modules; we cache the actual build artifacts (the /dist or /.next folders) across the entire organization.

If a developer on Team A builds the ui-components library, and a developer on Team B pulls the latest main branch, Team B's CI should not rebuild ui-components. It should download the artifact from the remote cache in milliseconds.

Pro Tip: Use a dedicated S3 bucket or the GitHub Actions Cache API for this, but ensure you use a 'Strict Content Hash'. If your cache key only includes the package version and not the hashes of its dependencies, you will end up with 'Cache Poisoning'—where an old version of a dependency is bundled into a new build.

Common Gotchas (What the docs don't tell you)

1. The Merge Commit Trap

GitHub Actions pull_request events run on a synthetic merge commit. If you diff against main, you are diffing the merge result against main, which can sometimes lead to unexpected packages being flagged as changed. Always ensure your discovery script uses git merge-base to find the true fork point.

2. Circular Task Dependencies

Task runners like Nx or Turborepo handle package dependencies well, but they don't always handle CI task dependencies (e.g., Package A's tests depend on Package B's build). If you are using a dynamic matrix, you must ensure that your matrix jobs are either self-contained (build + test in one job) or that you have a multi-stage matrix where all builds finish before tests start. I recommend self-contained jobs for simplicity unless your builds are massive.

3. Ghost Dependencies

If you use a shared tsconfig.json or eslint.config.js at the root, a change to that file should trigger a build for every package. Most discovery scripts miss this. You must explicitly add root-level config files to your path filters or as global dependencies in your turbo.json or nx.json.

The 2026 Takeaway

Don't let your monorepo CI be a black box. Today, audit your most expensive GitHub Action workflow. If it's running a single monolithic command like npm run test:all, replace it with a Dynamic Discovery Job using pnpm list --filter or nx show projects --affected. Transitioning to a graph-aware matrix will reduce your CI minutes by 40-70% overnight and provide your team with the granular feedback they need to move faster.