
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:
yamlname: 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:
textRequired 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:
yamlname: 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:
textfatal: 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.


