Why is my pull request "blocked"? Every reason GitHub stops a merge
A pull request has no conflicts, the code looks fine, and the merge button is grey with the words "Merging is blocked". In GitHub's API the same state is called blocked (the pull request field is mergeable_state, and the GraphQL field is mergeStateStatus). It means a rule on the target branch is not satisfied yet. The pull request itself is not broken.
The usual causes
- Required approvals are missing, or the number of approvals is below what the rule asks for.
- A review asked for changes and has not been dismissed or replaced.
- A new commit was pushed after an approval and the rule dismisses stale approvals, so approval is needed again.
- A code owner has not approved changes to files they own, when "Require review from Code Owners" is on.
- A required status check has failed, is still running, or never reported (see the post on "Expected: waiting for status to be reported").
- The branch must be up to date with the base branch before merging and it is behind.
- Open conversations must be resolved first.
- The rule requires signed commits, a linear history, or a successful deployment, and the pull request does not meet it.
- The branch uses a merge queue, so the pull request must be added to the queue instead of merged directly.
How to find the actual reason
- Open the pull request and scroll to the box above the merge button. GitHub lists each unmet requirement there, with a cross or a clock next to it.
- Open the branch protection rule (Settings, Branches) or the ruleset that applies and compare it with that list.
- Through the API, mergeable_state tells you the category only. The detail is in the reviews, the check runs and the protection rule.
Related states you will see
- dirty: the pull request has merge conflicts.
- behind: the branch is behind the base and the rule requires it to be up to date.
- unstable: a non-required check is failing. The pull request can still merge.
- draft: the pull request is a draft.
- unknown: GitHub has not finished working it out yet. Ask again a few seconds later.
Admins and bypass
Repository admins can often merge past a block unless "Do not allow bypassing the above settings" is on. A scheduled or automated merge made with a normal token or app follows the rules like everyone else, so if a human would be blocked, the tool is blocked too.
Why this matters for scheduled merges
A pull request that was ready when you scheduled it can be blocked by the time it is due: someone pushed a commit, an approval went stale, or a check is still running. A scheduler has to decide what to do. Merge Scheduler does not try to get around the block. It waits for checks that are still running, up to a limit you set, and skips the merge with the reason when the pull request stays blocked, so nothing merges at a time nobody planned.
Do this in Merge Scheduler: Schedule your first merge · Set up automatic revert for a failed deploy
Related: GitHub checks explained: check runs, commit statuses and required checks · "Expected: waiting for status to be reported": why a required check never starts · Why a scheduled merge should pin the commit you approved