How to Run a Monorepo Build with Path Filters in GitHub Actions

Path filters detect which packages changed so only those jobs run.

Run dorny/paths-filter to compute per-package change flags, then guard each build job with the matching output.

Steps

• Define filters mapping package names to their paths.
• Run the filter in a detect job and expose its outputs.
• Gate each package build on needs.detect.outputs.<pkg>.

Workflow

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.f.outputs.api }}
      web: ${{ steps.f.outputs.web }}
    steps:
      - uses: actions/checkout@v4
      - id: f
        uses: dorny/paths-filter@v3
        with:
          filters: |
            api: ['services/api/**']
            web: ['apps/web/**']
  build-api:
    needs: detect
    if: needs.detect.outputs.api == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "build api"

Gotchas

• On a push, the filter compares against the previous commit; on PRs, the base branch.
• A shared library change should map to every package that depends on it.

Related guides