Skip to content

Diagnose a pull request blocked by required checks

≈ 30 minutesIntermediate5 steps · 28 min estimated

Outcome. Work a "waiting for status to be reported" pull request through a decision tree — missing check versus failed check, trigger versus filter versus name — and fix the configuration without weakening protection.

Before you start: GitHub Actions fundamentals · Branch protection

The duration is an estimate of engaged work, not a timer — nothing here waits. Steps marked "Check" and "Practice" are verified in the browser; "Read" and "Lab" steps are yours to confirm.

  1. Read

    Required status checks, in detail

    ≈ 5 min

    Read this section and "Verifying protection actually works". Note that a required check is identified by its *name*.

  2. Read

    The diagnostic decision tree

    ≈ 8 min

    Read the tree and the three scenarios. Diagnose each scenario before opening its explanation.

  3. Predict

    Predict: filtered workflow, required check

    ≈ 1 min

    A subtle one, straight from GitHub's own troubleshooting page.

    A required check is the job `build` in a workflow with `on: pull_request: paths: ["scripts/**"]`. A pull request changes only README.md. What does the PR show?
    Why

    Per GitHub's documentation, a workflow skipped by a path filter, branch filter or a [skip ci] commit message leaves its checks Pending, and a required pending check blocks merging. (A *job* skipped by an `if:` conditional is different: it reports Success.) Either drop the path filter for the required workflow, or require a check that always reports.

  4. Lab

    Lab: debug a failing workflow

    ≈ 12 min

    A failing check is the other branch of the tree. Do the lab; mark this step when the workflow passes.

  5. Check

    Knowledge check: branch protection

    ≈ 2 min

    Closes the loop on what protection does and does not cover.

    Completes when the knowledge check on that page has been attempted.

When you are done: Lab: Design a pull request workflow. You can now debug required checks; this lab has you design the ruleset that requires them.

How did this go?