Matrix Builds for Multi-Site Monorepos

Teams that run several static sites — a marketing site, product docs, a blog, an API reference — often keep them in one repository with shared components, design tokens and configuration. The monorepo makes shared changes easy, but a naive CI workflow builds every site on every push. Fixing a typo in the blog rebuilds and redeploys the docs, the marketing site and the API reference, wasting minutes and creating deploys nobody asked for.

A dynamic matrix fixes that. One small job works out which sites a change affects, and a matrix build job creates one parallel job per affected site. This guide builds that workflow in GitHub Actions, including shared-package detection, per-site caching and a single required status check. It is part of GitHub Actions for Automated SSG Builds.

Prerequisites

• A monorepo with sites in separate folders, for example sites/docs, sites/blog, sites/marketing, and shared code in packages/.
• A package manager with workspaces (npm, pnpm or Yarn).
• Each site buildable with a single command from its folder.

The Layout

The workflow depends on being able to map paths to sites, so a predictable layout helps:

repo/
├── packages/
│   ├── ui/            # shared components, used by docs and marketing
│   └── tokens/        # design tokens, used by every site
├── sites/
│   ├── docs/          # Astro
│   ├── blog/          # Eleventy
│   └── marketing/     # Astro
└── package-lock.json

Step 1: Detect Affected Sites

The first job outputs a JSON list of affected sites. dorny/paths-filter evaluates named path filters against the pull request or push diff:

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      sites: ${{ steps.filter.outputs.changes }}
    steps:
      - uses: actions/checkout@v4
      - id: filter
        uses: dorny/paths-filter@v3
        with:
          filters: |
            docs:
              - 'sites/docs/**'
              - 'packages/ui/**'
              - 'packages/tokens/**'
              - 'package-lock.json'
            blog:
              - 'sites/blog/**'
              - 'packages/tokens/**'
              - 'package-lock.json'
            marketing:
              - 'sites/marketing/**'
              - 'packages/ui/**'
              - 'packages/tokens/**'
              - 'package-lock.json'

The changes output is a JSON array of filter names that matched, such as ["docs","marketing"]. Keeping the filters in the workflow file makes the dependency map explicit and reviewable. For larger monorepos, a workspace tool's own "affected" command — turbo ls --affected or nx show projects --affected — derives the same list from the package graph automatically.

Step 2: Build Each Affected Site

The build job turns that list into a matrix:

  build:
    needs: changes
    if: needs.changes.outputs.sites != '[]'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        site: ${{ fromJSON(needs.changes.outputs.sites) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version-file: .nvmrc, cache: npm }
      - uses: actions/cache@v4
        with:
          path: sites/${{ matrix.site }}/node_modules/.astro
          key: ${{ matrix.site }}-assets-${{ github.sha }}
          restore-keys: ${{ matrix.site }}-assets-
      - run: npm ci
      - run: npm run build --workspace sites/${{ matrix.site }}
      - uses: actions/upload-artifact@v4
        with:
          name: site-${{ matrix.site }}
          path: sites/${{ matrix.site }}/dist

Three details make this work well:

• The if guard. A matrix built from an empty list is an error in GitHub Actions. When a change touches only the README, the list is [] and the build job is skipped instead of failing.
• fail-fast: false. A broken blog build should not cancel the docs build; each site reports its own result.
• Per-site cache keys. Each site gets its own asset cache, so the docs site's image cache is never overwritten by the blog's.

Step 3: One Required Check

Branch protection needs stable check names, but matrix jobs are named build (docs), build (blog) and so on, and a skipped matrix produces no jobs at all. Add a summary job and make it the only required check:

  ci-ok:
    needs: [changes, build]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: |
          result="${{ needs.build.result }}"
          if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then exit 1; fi

if: always() makes it run even when build was skipped or failed. It passes when every affected site built, or when no site was affected, and fails otherwise.

The same pattern works for any number of sites. When a fourth site is added to the repository, it needs a filter entry and a deploy environment; the required check, branch protection and the rest of the workflow stay as they are. That is the main reason to avoid listing matrix job names in branch protection: every new site or rename would otherwise need an administrator to update the repository settings, and a forgotten update either blocks all merges or silently stops requiring the new site's build.

Step 4: Deploy What Changed

Deployment follows the same matrix. A deploy job with the same matrix.site and needs: build downloads the matching artifact and deploys it to that site's target, using an environment per site so each has its own secrets and protection rules:

  deploy:
    needs: [changes, build]
    if: github.ref == 'refs/heads/main' && needs.changes.outputs.sites != '[]'
    strategy:
      matrix:
        site: ${{ fromJSON(needs.changes.outputs.sites) }}
    environment: ${{ matrix.site }}-production
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with: { name: 'site-${{ matrix.site }}', path: dist }
      - run: ./scripts/deploy.sh ${{ matrix.site }} dist

Sites that did not change are not redeployed, so their CDN caches stay warm and their deploy history stays meaningful. It also makes rollbacks simpler: when the blog breaks, its deploy history contains only blog changes, and rolling it back cannot accidentally revert an unrelated docs release that went out in the same merge. Give each site's environment its own protection rules, so a marketing launch can require approval from the marketing lead without slowing down documentation fixes.

Keeping the Map Honest

The path filters are a dependency map written by hand, and hand-written maps drift. A site starts importing packages/ui and nobody adds the path to its filter, so a UI change silently skips that site's build. Two safeguards help:

1. A nightly full build. A scheduled workflow that builds every site regardless of changes catches anything the filters missed within a day.
2. Derive filters from the workspace graph. Tools such as Turborepo and Nx know which packages each site depends on; using their affected commands removes the hand-written map entirely. See Remote Caching with Turborepo for SSG Monorepos.

Measured Impact

A company with three sites — Astro docs, an Eleventy blog and an Astro marketing site — in one repository moved from a single job that built everything to the dynamic matrix. With 82% of pull requests touching one site, median wall-clock CI time fell from 14 to 4.5 minutes and monthly runner minutes fell by 61%. Shared package changes built all three sites in parallel in about five minutes. Unnecessary production deploys, previously three per merge, dropped to the one site that changed.

Pitfalls & Rollback

• Empty matrix. Always guard with an if on the list.
• Push events with no base. On the first push of a new branch, path filters may compare against the default branch; check base settings for push events.
• Drifted filters. Add the nightly full build.
• Required matrix jobs. Require the summary job, never the individual matrix entries.
• Rollback: replace the matrix with a static list of all sites; everything builds again, correctly if slowly.

Conclusion

In a multi-site monorepo, building everything on every change wastes time and produces deploys nobody needs. Compute the affected sites from changed paths, build and deploy them with a dynamic matrix, keep per-site caches and environments, and gate merges on a single summary check. Back the path map with a nightly full build or derive it from the workspace graph, and CI time tracks the size of the change rather than the size of the repository.

FAQ

What is a dynamic matrix in GitHub Actions?

A matrix whose values are produced at run time by an earlier job instead of written in the workflow file. A first job outputs a JSON list, for example the sites affected by a change, and the build job uses fromJSON on that output as its matrix, creating one job per list entry.

How do I detect which sites a change affects?

Compare the changed files against each site's directory and against shared directories. A change inside sites/docs affects only docs; a change to packages/ui or the lockfile affects every site that depends on them. dorny/paths-filter or a workspace tool's affected command can compute this.

What happens when no site is affected?

The matrix would be empty, and GitHub Actions fails a job whose matrix is empty. Guard the build job with an if condition that checks the list is not empty, so the workflow succeeds without building anything.

How do I make a matrix build a required status check?

Matrix job names change with their values, which makes them awkward as required checks. Add a final summary job that needs the matrix job and always runs, fails if any matrix entry failed, and make that single job the required check.

Related

• Parent: GitHub Actions for Automated SSG Builds — every workflow pattern.
• Building Astro Sites with GitHub Actions — the single-site workflow each matrix entry runs.
• Remote Caching with Turborepo for SSG Monorepos — graph-aware affected detection.
• Deploying to Multiple Environments From One Workflow — environments and approvals.
• Sharing Build Cache Across CI Runners — keeping per-site caches warm.