In a GitHub Actions monorepo, how would you design paths filters without blocking merges?

## The tension A monorepo wants two things that pull against each other. Cost and latency say: only run the API suite when the API changed. Merge policy says: this check must pass before anything merges. GitHub Actions resolves them only if you understand one asymmetry. **A workflow that never runs reports nothing.** If `on: pull_request: paths: ['services/api/**']` excludes the diff, GitHub creates no run, so no check named after that workflow's jobs ever appears. A required check that never reports stays *pending*, and the pull request is blocked indefinitely — a merge failure caused by a *saving* measure. **A job skipped by a conditional reports success.** If the workflow runs and a job's `if:` evaluates false, the job is skipped, and skipped jobs are treated as successful for required-status-check purposes. The check appears, resolves, and merging proceeds. Every viable design is built on that distinction. ## Design A: the stub companion workflow Keep the path filter on the real workflow and add a second workflow file with the **same workflow name and the same job names**, triggered on the complementary `paths-ignore`, doing nothing: ``` # ci-api.yml on: pull_request: paths: ['services/api/**'] # ci-api-skip.yml on: pull_request: paths-ignore: ['services/api/**'] ``` Exactly one of the two runs for any diff, and either way a check with the required name reports success or the real result. Strengths: the expensive workflow genuinely never starts, so no runner minutes at all; the mechanism is explicit and easy to explain. Weaknesses: the two files must be kept in lockstep — every job-name change has to be mirrored, and a drifted stub silently reintroduces the blocked-merge failure. With a dozen components you are maintaining two dozen files and the filters must partition the diff space exactly. ## Design B: always run, decide inside Drop `paths` from the trigger. One cheap job computes what changed and exposes it as outputs; expensive jobs gate on those outputs: ``` jobs: changes: outputs: api: ${{ steps.filter.outputs.api }} api-tests: needs: changes if: needs.changes.outputs.api == 'true' ``` Change detection can be a `git diff` against the base ref in a `run:` step, or a dedicated change-filter action (`dorny/paths-filter` is the widely used one) — pinned by SHA like any third-party action. The cost is one short job per pull request; the benefit is that every check reports, filter logic lives in one place, and it can express things trigger filters cannot: "run the integration suite if either the API *or* the shared library changed", "always run everything for a release branch", "run everything when the workflow file itself changed". At scale, front the whole thing with one **aggregate gate job** that is the only required check: ``` ci-gate: needs: [api-tests, web-tests, lint] if: always() steps: - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') run: exit 1 ``` `if: always()` makes it run even when a dependency was skipped or failed, and `needs.*.result` lets it fail when any real job failed while tolerating skips. Now the merge policy references exactly one stable check name, and you can add, split or rename underlying jobs without touching branch policy — which in a large org is worth more than the runner minutes, because renaming a required check is an administrative change, not a code change. ## Choosing between them A handful of components with genuinely expensive suites and stable job names: Design A is fine and gives the best cost profile. A repository with many components, frequent job churn, or cross-component dependencies: Design B, because correctness of the merge gate matters more than the seconds spent on a detection job, and because "why can't I merge" incidents are expensive in engineer time. A hybrid is common and reasonable: path-filter the workflows nobody requires (nightly perf, docs preview, artifact publishing), and use always-run-plus-gate for the ones merge policy depends on. The rule of thumb worth stating: **if a check is required, do not filter it at the trigger.** ## Details that bite Path filters accept the same glob vocabulary as branch filters, `*` not crossing `/` while `**` does, and `paths` cannot be paired with `paths-ignore` on the same event — use a `!` negation inside the positive list. `paths` is available on `push` and `pull_request` only; `schedule` and `workflow_dispatch` have no diff to filter, so those workflows always run in full. On `push`, the filter examines the files changed in the pushed commits; on `pull_request`, the pull request's whole diff — so a stack of commits can match on a pull request while an individual push did not. Finally: whichever design you choose, the workflow files themselves should be inside the filter set. A change to `.github/workflows/**` that alters what CI does must trigger CI, or you can merge a workflow edit that no run ever exercised.