# Monorepo CI on GitHub Actions: run only what changed, without the required-check trap

A path-filtered workflow that does not run leaves a required check Pending. How to run only the changed packages, with one gate job as the required check.

By Grant Unwin, published 2026-11-06. Checked against GitHub's documentation on 2026-11-17. The web page: https://www.runners.io/blog/github-actions-monorepo-required-check-trap

A workflow that a paths filter skips reports nothing, so a required check from it stays “Pending” and blocks the pull request. Keep the filtering inside one workflow instead: a job lists the packages a change touches, the tests run for those, and a final job that always runs is the only required check. In a test repository of 5 packages, the detection script picked 1 package for a one-package change and all 5 for a change to a root file such as package.json.

**In short**

- A workflow skipped by a paths filter reports nothing, so a required check from it stays Pending and blocks the pull request.
- Filter inside one workflow: a job lists the changed packages as JSON, a matrix tests them, and a gate job that always runs is the one required check.
- A skipped job reports success, so the gate reads its dependencies' results itself and fails on failure or cancelled.
- In a 5-package test repository the detection script picked 1 package for a one-package change and all 5 for a root-file change.
- In our own repository, 45 of the 46 workflows that start on a push or pull request are path-filtered, so none can be required.

## What is the required-check trap?

A required status check has to report a result before a pull request can merge. A path-filtered workflow that does not start reports nothing at all, so nothing has failed and nothing has passed: the check just never arrives. GitHub’s own example is a workflow that runs only when a pull request changes files in `scripts`. A pull request that changes only a file in the repository root does not start it, and if its `build` job is required, the pull request is blocked with “Waiting for status to be reported.” The rows below are from [GitHub’s page on troubleshooting required status checks](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks), read on the date this post was last checked, and they are the rows that matter here. [The workflow syntax reference](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) says the same of path filters.

| Cause | Result | GitHub says to do |
| --- | --- | --- |
| A workflow is skipped by path filtering, branch filtering or a commit message | Associated checks stay in a “Pending” state and block merging | Avoid requiring workflows that can be skipped. |
| A job is skipped by a conditional | The job reports “Success” | See the conditions page. |
| A job depends on a failed job | The dependent job is skipped and may not block merging | Use always() with needs for required checks that depend on other jobs. |

The first row is the trap, and the second and third are why the way out works. A job skipped by a conditional counts as a success, so it is safe to skip jobs inside a workflow that always starts. But a job that needs a failed job is skipped too, and a skipped job reports success, so a gate has to ask for its dependencies’ results and not rely on its own status. The [post on running less](https://www.runners.io/blog/speed-up-github-actions-by-running-less) has the path-filter details and a single-package version of this gate. This post is about the part it leaves out: a repository with several packages, where the question is which of them to test.

## How do I run only the packages that changed?

Put one workflow with no `paths` filter in front of everything. A first job works out which packages the pull request touched and passes them on as JSON. A second job runs once for each of them, as a matrix. A third, the gate, always runs and fails if either of the others failed. The script below does the first step with `git diff` and `jq`, so there is no third-party action to pin.

```bash
#!/usr/bin/env bash
# Prints packages=<JSON array> for GITHUB_OUTPUT: the packages a change touches.
# A file under packages/<name>/ maps to that package. A file elsewhere (a lockfile,
# the workflow, shared tooling) maps to every package, except documentation.
# With no base commit (a merge queue run) every package is listed.
set -euo pipefail
base="${1:-}"
head="${2:-HEAD}"

all() { ls packages | sort; }

if [ -z "$base" ]; then
  list=$(all)
else
  changed=$(git diff --name-only "$base" "$head")
  if [ -z "$changed" ]; then
    list=""
  elif printf '%s\n' "$changed" | grep -qvE '^(packages/|docs/|.*\.md$)'; then
    list=$(all)
  else
    list=$(printf '%s\n' "$changed" | { grep -E '^packages/' || true; } | cut -d/ -f2 | sort -u)
  fi
fi

printf 'packages=%s\n' "$(printf '%s' "$list" | jq -R . | jq -sc 'map(select(length > 0))')"
```

```yaml
name: ci
on:
  pull_request:
  merge_group:
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
permissions:
  contents: read
jobs:
  changes:
    runs-on: ubuntu-slim
    timeout-minutes: 5
    outputs:
      packages: ${{ steps.detect.outputs.packages }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - id: detect
        env:
          BASE: ${{ github.event.pull_request.base.sha }}
        run: ./scripts/changed-packages.sh "$BASE" HEAD >> "$GITHUB_OUTPUT"

  test:
    needs: changes
    if: needs.changes.outputs.packages != '[]'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        package: ${{ fromJSON(needs.changes.outputs.packages) }}
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - run: make -C "packages/${{ matrix.package }}" test

  ci:
    if: always()
    needs: [changes, test]
    runs-on: ubuntu-slim
    timeout-minutes: 5
    steps:
      - env:
          RESULTS: ${{ join(needs.*.result, ',') }}
        run: |
          echo "results: $RESULTS"
          case ",$RESULTS," in
            *,failure,*|*,cancelled,*) exit 1 ;;
          esac
```

We linted this with actionlint 1.7.12 and did not run it on GitHub. The paths, the `make` target and the package names are placeholders for yours. What we did run is the detection script and the gate’s decision, in the next two sections. Two choices are worth knowing about. The `changes` job checks out with `fetch-depth: 0` so the base commit is there to diff against, and the matrix job runs only when the list is not empty, so it is never handed an empty matrix.

## Does the detection pick the right packages?

We made a throwaway repository with five packages and a documentation folder, committed a change of each kind on a branch and ran the script against the base. The output is below. The line that matters most is the root file: anything that is not in a package, such as a lockfile or the workflow itself, runs every package, because a change there can affect all of them. Documentation alone runs none.

| Change | Output | What the workflow does |
| --- | --- | --- |
| One file in packages/api | \["api"\] | one test job |
| Files in packages/api and packages/web | \["api","web"\] | two test jobs |
| README.md and docs/guide.md only | \[\] | no test job, gate passes |
| A file in packages/billing and docs/guide.md | \["billing"\] | one test job |
| package.json at the root | \["api","billing","docs-site","web","worker"\] | five test jobs |
| .github/workflows/ci.yml | \["api","billing","docs-site","web","worker"\] | five test jobs |
| No base commit (what a merge queue run should pass; not run on GitHub) | \["api","billing","docs-site","web","worker"\] | five test jobs |
| No change between base and head | \[\] | no test job, gate passes |

This maps files to packages and nothing more. It does not know that `web` imports `api`, so a change to `api` will not test `web`. A build tool that knows the dependency graph, such as Bazel or Gradle, can say which packages a change affects, and its list can feed the same matrix in place of the script.

## What should the one required check be?

The gate job, here named `ci`, and nothing else. It always runs, so it always reports. It passes when every job it waits for passed or was skipped on purpose, and fails when one failed or was cancelled. Because it asks for `needs.*.result` itself, a failed test job cannot hide behind a skipped gate. We ran the workflow’s own `case` statement on five sets of results.

| Results of changes, test | Gate | Why |
| --- | --- | --- |
| success,success | green | Both jobs passed. |
| success,skipped | green | A documentation-only change: the tests were skipped on purpose. |
| success,failure | red | A package's tests failed. |
| success,cancelled | red | The run was cancelled. |
| failure,skipped | red | Detection failed, so the tests never started. |

One practical detail: GitHub says a required check must have completed successfully in the repository during the past seven days, so make sure the gate has run, by opening a pull request, before you require it.

## Do I need anything extra for a merge queue?

Yes: the workflow has to trigger on `merge_group` as well, which the file above does. [GitHub](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)says a merge queue needs this because `merge_group` is a separate event from `pull_request` and `push`, and without it the required check is never reported and the merge fails. A merge queue run should have no pull request base for the script to diff against, and we have not run the workflow on GitHub to see, so the script lists every package when it is given no base. That is our choice, and a deliberate one: the queue is the last check before the default branch, and it is cheap to be wrong in the safe direction.

## When is a workflow-level paths filter still fine?

When the check is not required. A workflow that builds the documentation site, or posts a preview, can sit behind a `paths` filter and simply not run when nothing it cares about changed: nobody is waiting on it, so nothing is blocked. The trap needs both halves, a filter that skips and a rule that requires the result. Remove one half. The [pricing post](https://www.runners.io/blog/github-actions-pricing-2026) shows what the minutes you do not run are worth, and the [calculator](https://www.runners.io/calculator) prices a month of the ones you do. Each matrix job bills at least a whole minute, and the [runner size guide](https://www.runners.io/blog/github-actions-runner-size-guide) says when a bigger runner for one of them is worth the rate.

## What does this look like in a large repository?

Our own repository is a monorepo with many service-specific workflows. We counted its workflow files on 17 November 2026 by reading the `on:` block of each: there are 154, of which 46 start on a push or a pull request, and 45 of those 46 are filtered by path to the service they test. None of the 45 can be a required check, for the reason above. The 46th is a gate that has no filter. It reads the other workflows’ path filters, works out which of them should have started for the files in the pull request, and reports one commit status: pending while checks are outstanding, failure if one fails or never started, and success only once every one of them has passed.

> **Two ways to one check**
>
> The gate in this post suits one workflow with many packages: the filtering is inside it, so it always starts. A repository with a separate workflow for each service needs the other shape, a separate gate that works out what should have run. Both end in a single check that always reports, which is the kind that is safe to require in a path-filtered repository.

If you take one thing from this: do not require a workflow that a path filter can skip. Require something that always runs and knows what it was waiting for. Build times measured on GitHub’s runner and on ours are on our [faster GitHub Actions runners, measured](https://www.runners.io/faster-github-actions) page.

## Sources

- [Troubleshooting required status checks](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks)
- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
- [Events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)

## Frequently asked questions

### Why is my required check stuck on Waiting for status to be reported?

The workflow that reports it did not start. GitHub says a workflow skipped by path filtering, branch filtering or a commit message leaves its checks Pending, and a pull request that requires them is blocked. Do not require a workflow a filter can skip.

### Does a skipped job count as passing for a required check?

Yes. GitHub says a job skipped by a conditional reports Success. A job whose dependency failed is also skipped and may not block merging, so a gate job needs always() with needs, and must read the results itself.

### How do I run only the changed packages in a GitHub Actions monorepo?

Use one workflow with no paths filter. A first job lists the changed packages from git diff as JSON, a matrix job runs the tests for each, and a final gate job that always runs is the only required check.

### Does a merge queue need anything extra?

Yes. The workflow must also trigger on merge\_group, which GitHub says is separate from pull\_request and push. Without it the required check is never reported and the merge fails.
