Close up of green indicator lights on a server rack panel.

Photo by panumas nikhomkhai on Pexels

You push a pull request that changes only documentation, and your required CI check fails because it skipped running. GitHub branch protection blocks the merge anyway, demanding a green checkmark that will never arrive.

This trap catches teams that try to save GitHub Actions runner minutes by filtering path changes. It leaves the pull request permanently stalled.

The problem with paths filtering

A standard workflow optimization looks like this:

yaml
name: Test Suite

on:
  pull_request:
    paths:
      - 'src/**'
      - 'package.json'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

If your repository requires the Test Suite check to pass before merging into main, editing a markdown file breaks your pipeline. You edit README.md, commit, and push.

On the pull request page, you see this message:

text
Required status check "Test Suite" is expected. At least 1 approving review is required by reviewers with write access.

The check is not red. It is grey, marked as pending indefinitely. GitHub Actions evaluated the paths trigger, saw no matching files, and skipped the entire workflow run. Because the workflow never started, it never reported a status to the GitHub commit status API.

The branch protection rule does not understand that you skipped the run intentionally. It only knows that a job named Test Suite must report success, and nothing arrived.

The fix using a conditional job wrapper

To satisfy branch protection, the workflow file must execute on every single pull request, without exception. The workflow runs, but the expensive commands do not.

Remove the paths filter from the top-level on: trigger. Instead, run a fast preliminary job that detects file changes, then gate your heavy jobs behind that check. A clean way to handle this without external third-party actions is using git directly against the target branch.

Replace your workflow with this pattern:

yaml
name: Test Suite

on:
  pull_request:
    branches:
      - main

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      should_run: ${{ steps.check.outputs.should_run }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: check
        run: |
          DIFF=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
          MATCH=$(echo "$DIFF" | grep -E '^(src/|package\.json)' || true)
          if [ -n "$MATCH" ]; then
            echo "should_run=true" >> "$GITHUB_OUTPUT"
          else
            echo "should_run=false" >> "$GITHUB_OUTPUT"
          fi

  test:
    needs: changes
    if: needs.changes.outputs.should_run == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  # This is the single job you mark as required in branch protection
  ci-gate:
    needs: [changes, test]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Evaluate results
        run: |
          TEST_RESULT="${{ needs.test.result }}"
          if [ "$TEST_RESULT" = "failure" ] || [ "$TEST_RESULT" = "cancelled" ]; then
            echo "Tests failed or were cancelled."
            exit 1
          fi
          echo "Checks passed or were legitimately skipped."
          exit 0

Why this works

Branch protection rules look for a specific job name, not the parent workflow name.

In the updated workflow, the ci-gate job always executes because it has if: always(). If code changes match src/**, test runs. If test succeeds, ci-gate checks its result, sees success, and exits 0.

If you only touch README.md, changes evaluates to false. GitHub Actions skips the test job entirely. Its status becomes skipped.

Then ci-gate runs. In GitHub Actions logic, a skipped dependency does not count as a failure. The bash script in ci-gate verifies that test did not fail, decides everything is fine, and exits with status 0.

In your GitHub repository settings under Branches, change your required status check from test to ci-gate. Every pull request now reports a clean, green checkmark in less than ten seconds, even when no tests run.

The shallow clone gotcha

The script above uses actions/checkout@v4 with fetch-depth: 0 in the changes job.

By default, the checkout action fetches only a single commit:

yaml
- uses: actions/checkout@v4 # Defaults to fetch-depth: 1

If you leave out fetch-depth: 0, the line git diff --name-only origin/${{ github.base_ref }}...HEAD fails. The runner does not possess the commit history of the base branch. Git throws this error into your action logs:

text
fatal: ambiguous argument 'origin/main...HEAD': unknown revision or path not in the working tree.

When git fails like that, your script continues with an empty string, marks should_run=false, and skips the test suite even when code changed. Setting fetch-depth: 0 fetches the full history so git can compare the fork point reliably. On massive repositories with tens of thousands of commits where a full clone is too slow, fetch only the base ref explicitly:

yaml
- uses: actions/checkout@v4
- run: git fetch origin ${{ github.base_ref }} --depth=1

This retrieves just enough history to compute the diff without pulling the entire project history down to the runner.


Published by the Old Lane Developer Desk. This article was drafted with AI assistance.

More in Bash