All posts

Blog ·

Why a skipped workflow blocks your merge

You add a path filter so the tests don’t run for a docs change. The docs change then can’t be merged, because the check it needs never comes.

What happens

Say your tests are a required check on main, and you only want them to run when the code changes:

on:
  pull_request:
    paths:
      - 'src/**'

Someone opens a pull request that only touches README.md. The workflow doesn’t start, so it never reports. GitHub is still waiting for the check the branch rules require, and the pull request shows it as Expected — Waiting for status to be reported for good. Nobody can merge it without an admin overriding the rules.

GitHub’s docs say a workflow skipped by path filtering, branch filtering or a commit message leaves its checks pending, and they block merging. A job skipped by an if: condition is different: it reports success.

The fix: filter jobs, not workflows

So keep the workflow running on every pull request, and decide inside it which jobs run. A first job looks at what changed. The others run only when their files did. One last job sums it up, and that one is the required check:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  changes:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      app: ${{ steps.filter.outputs.app }}
      docs: ${{ steps.filter.outputs.docs }}
    steps:
      - uses: actions/checkout@v7
      - id: filter
        uses: dorny/paths-filter@v4
        with:
          filters: |
            app:
              - 'src/**'
              - 'package.json'
              - 'pnpm-lock.yaml'
              - '.github/workflows/ci.yml'
            docs:
              - 'docs/**'

  test:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - run: npm ci && npm test

  docs:
    needs: changes
    if: needs.changes.outputs.docs == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - run: npx markdownlint-cli2 "docs/**/*.md"

  # The one required check. It passes when every job above passed or was
  # skipped, and fails when one failed or was cancelled.
  ci-ok:
    if: always()
    needs: [changes, test, docs]
    runs-on: ubuntu-latest
    timeout-minutes: 2
    steps:
      - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
        run: exit 1

Then, in the branch rules, require ci-ok and nothing else. A docs-only pull request skips test, ci-ok passes, and it merges. A code change runs test, and ci-ok fails if it fails.

ci-ok needs both of its lines. if: always() makes it run when a job before it failed or was skipped, which is when it has something to say; without it, it would be skipped too and report success. And it checks for cancelled as well as failure, so a run cut short doesn’t count as a pass.

Four ways it still goes wrong

The filter forgets a file the tests depend on

Put the lockfile, the package manifest and the workflow file itself in the filter. A dependency bump that only touches pnpm-lock.yaml should run the tests, and so should a change to how they run.

The filter matches every pull request anyway

If every pull request bumps a version in package.json, a filter that includes it runs the tests every time. Check it against your last pull requests before you count on the savings: gh api repos/OWNER/REPO/pulls/123/files -q '.[].filename' shows what one touched.

You rename a required job

Required checks are matched by name. Rename test, or the value a matrix puts in its name, and GitHub waits for the old name forever. With one ci-ok as the only required check, you can rename everything else.

A job after it is skipped too

A job that needs a skipped job is skipped as well, even when it has nothing to do with the files. A build or deploy after test stops running on docs changes. Give it if: ${{ !failure() && !cancelled() }}: it then runs when the jobs before it passed or were skipped.

Finding this in your CI

Gating jobs on what changed is one of the first things /make-ci-more-efficient looks for. It measures how many minutes your jobs spend on changes they don’t test, reads your required checks before it touches anything, and writes the gate job above for you when it’s worth it.

npx skills add https://checklane.sh --skill make-ci-more-efficient -a claude-code

Then type /make-ci-more-efficient in Claude Code, or tell it your CI is slow.