GitHub checks explained: check runs, commit statuses and required checks
The green tick or red cross on a pull request is a summary of checks. Checks are results that tools attach to a specific commit. Knowing what they are makes "blocked" and "waiting for status" much easier to understand.
Two kinds of result on a commit
- Check runs come from the Checks API. GitHub Actions jobs are check runs, and so are results from apps such as code scanners. A check run has a status (queued, in progress, completed) and, once completed, a conclusion.
- Commit statuses come from the older Status API. Some CI systems still report this way. GitHub combines them into one state: success, pending, failure or error.
Conclusions of a check run
A completed check run ends as success, failure, neutral, cancelled, skipped, timed out, action required or stale. For required checks, success, skipped and neutral count as passing. The others do not.
Checks belong to a commit, not to a pull request
Every check is attached to a commit SHA. Push a new commit and the checks start again for the new SHA. Workflows triggered by pull_request run on a temporary merge of the pull request into its base branch, and report their result against the head commit.
Required checks
In a branch protection rule or ruleset you can mark checks as required. GitHub then blocks the merge until each required check has reported a passing result for the head commit. Checks you did not mark as required can fail and the pull request can still merge. GitHub shows that state as unstable.
Checks before the merge, deploy after it
Pull request checks run before the merge, on the proposed change. The deploy runs after the merge, on the base branch. They are separate gates, and a green pull request does not prove the deploy will work.
What a scheduler should do with them
- Read the checks again at merge time, not when you scheduled. They may have changed.
- Wait for checks that are still running, within a limit.
- Skip the merge when a check has failed, and say which one.
- Treat "no checks at all" as a fact to report, not as proof the change is safe.
Where Merge Scheduler fits
Merge Scheduler reads both check runs and commit statuses for the pinned commit when the release is due. A failed check skips the merge, a running one makes it wait up to your limit, and a commit with no checks is reported as "none found". After the merge it watches the deploy.
Do this in Merge Scheduler: Schedule your first merge
Related: Why is my pull request "blocked"? Every reason GitHub stops a merge · A pull request with no checks: is it safe to merge to production? · CI/CD gates: checks before the merge and checks after the deploy