Published
GitHub Pull Request Checks: Run and Require Tests
Short answer
A GitHub pull request check is a status reported on the PR's latest commit, usually by a GitHub Actions job. To make tests gate merging, run them in a workflow triggered by pull_request, then mark the job as a required status check in branch protection or a ruleset. The check must report success, skipped or neutral before the PR can merge.
Last updated: 2026-11-10
What are pull request checks?
Pull request checks are the results of automated jobs that run against the commits in a pull request, shown in the Checks area at the bottom of the PR. A check can come from a GitHub Actions workflow, or from an external CI service that reports a commit status. Each check is tied to a commit SHA.
A check only blocks merging when you mark it as required. Until then it is advisory: the PR shows red, but the merge button still works for anyone with permission.
How do I run tests as a pull request check?
Create a workflow that runs on pull_request. This example runs Playwright tests:
name: e2e
on:
pull_request:
branches: [main]
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
The job name, here e2e, is what shows up in the PR and what you select as a required check. For larger suites, split the run across shards; see Run Playwright in GitHub Actions with parallel shards.
How do I make a check required?
Open the repository settings and add a branch protection rule or a ruleset for your default branch, then turn on the option to require status checks to pass before merging. Search for the job name and add it.
GitHub's documentation on protected branches gives several points to know:
- Required checks can be checks or commit statuses, and they must report a passing outcome (successful, skipped or neutral) before changes can merge.
- Make job names unique across all workflows. Duplicate names can produce ambiguous results and block pull requests from merging.
- The "Require branches to be up to date before merging" option (strict mode) makes the branch match the base branch before merging. It catches incompatible changes but needs more builds, because every PR must re-run after the base moves.
- A merge queue gives the same protection without asking authors to update their branches and wait. The queue runs the required checks against the latest target branch and any PRs ahead of it.
- Rulesets are not limited to one rule per branch, which branch protection is.
Why is my required check stuck on "Waiting for status to be reported"?
This is the most common problem. GitHub's troubleshooting page says that if a workflow is skipped because of path filtering, branch filtering or a commit message, the checks it would have produced stay in a Pending state and block merging. Its example is a PR that changes only a root file, so a workflow with a paths filter never runs and the required build check waits forever.
Ways to deal with it:
- Do not put a
pathsfilter on a workflow that provides a required check. Let the workflow always run, and skip work inside it if you need to. - Use one final "gate" job. Make a job that depends on the others with
needsand run it withif: always(), then require only that job. GitHub's guidance for required checks that depend on other jobs is to usealways()withneeds, because a job skipped after a dependency fails may not block the merge. - Know how skipped jobs count. A job skipped by a conditional reports success, so it passes a required check.
Two more cases from the same page. If a check and a commit status share a name, both must pass when that name is required. And a check must succeed on the latest commit SHA; results from earlier commits do not count, so push a new commit and the checks must run again.
How do I stop flaky tests from blocking merges?
A required check that fails at random teaches people to click "re-run" without reading. Detect flakes with retries (Playwright reports a test that fails and then passes as flaky), then fix the cause. Our flaky tests guide covers detection and the usual fixes. To debug a CI failure you cannot watch, record traces on retry and upload them as an artifact; see the Playwright Trace Viewer guide.
What a required check does not tell you
A green required check says the tests that ran passed. It does not say whether those tests cover the change, whether anyone reviewed them, or whether a coding agent weakened an assertion to get to green. When agents open most of your PRs, those questions are the ones that matter.
TestChimp adds that view on top of your CI. It links Playwright tests to written scenarios in your repo, shows coverage against them, and flags agent-edited tests for review, so you can see both whether the check passed and which tests deserve trust. See How to trust AI-written tests.
Frequently asked questions
What are GitHub pull request checks?
They are automated results attached to the latest commit of a pull request, typically from GitHub Actions workflows or an external CI service. They appear in the Checks area of the PR.
How do I require tests to pass before merging on GitHub?
Run the tests in a workflow triggered by pull_request, then add the job as a required status check in branch protection or a ruleset. The check must report successful, skipped or neutral to allow the merge.
Why does my required check say Waiting for status to be reported?
The workflow that provides it was probably skipped, for example by a paths filter, so the check never reported. GitHub says skipped workflows leave their checks pending. Remove the filter or require a single gate job that always runs.
Does a skipped job pass a required check?
A job skipped by a conditional reports success. A job that depends on a failed job is skipped and may not block merging, so GitHub recommends always() with needs for required checks that depend on other jobs.
What does require branches to be up to date do?
It forces the PR branch to match the base branch before merging. It catches incompatible changes but needs more builds. A merge queue gives similar protection without authors updating branches by hand.
Does a passing check mean the tests are good?
No. It means the tests that ran passed. Coverage, review status and agent edits to tests need a separate view, which TestChimp provides.
Make the green check mean something
Keep required checks on your PRs and add visibility into coverage and agent-edited tests. 14-day free trial, no credit card.