A practical pattern for monorepo CI with path filters, matrix builds, caching, and deployment guards that keep feedback fast as teams scale.
GitHub Actions for Monorepos: Fast CI Without Pipeline Chaos
Monorepos improve shared ownership and cross-service refactoring, but CI pipelines can become slow and expensive when every pull request runs every job. The fix is not one giant workflow file. The fix is a clear build contract with targeted execution, predictable caching, and strict release gates.
Use three layers:
- Change detection to decide which services are impacted.
- Targeted build/test matrix for only those services.
- Protected deploy workflows that run only from trusted branches and environments.
name: ci
on:
pull_request:
push:
branches: [main]
jobs:
detect:
runs-on: ubuntu-latest
outputs:
services: ${{ steps.set.outputs.services }}
steps:
- uses: actions/checkout@v4
- id: set
run: |
CHANGED=$(git diff --name-only origin/main...HEAD | cut -d/ -f1,2 | sort -u)
SERVICES=$(echo "$CHANGED" | grep '^services/' | cut -d/ -f2 | jq -R -s -c 'split("\n")[:-1]')
echo "services=$SERVICES" >> $GITHUB_OUTPUT
This keeps you from building unrelated applications when docs or other folders change.
test:
needs: detect
if: ${{ needs.detect.outputs.services != '[]' }}
strategy:
matrix:
service: ${{ fromJson(needs.detect.outputs.services) }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run lint --workspace=services/${{ matrix.service }}
- run: npm run test --workspace=services/${{ matrix.service }}
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
Pair this with protected environments and manual approvals for production.
- Keep shared workflows in reusable workflow files.
- Cache dependencies, but include lockfile hash in cache keys.
- Use concurrency groups to cancel stale PR runs.
- Fail fast on lint and type checks before heavy integration suites.
With this model, monorepo CI stays fast as service count grows.
