Skip to content

docs(auto-merge): reading mergeStateStatus BLOCKED (required vs non-required) #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 1 commit into from
Jul 18, 2026
Merged

docs(auto-merge): reading mergeStateStatus BLOCKED (required vs non-required) #121

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions skills/github-project/references/auto-merge-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,23 @@ gh api "repos/OWNER/REPO/actions/runs?per_page=5" --jq \
gh api repos/OWNER/REPO/actions/runs/RUN_ID/rerun -X POST
```

## `mergeStateStatus: BLOCKED` — Check Required vs Non-Required Checks First

`BLOCKED` does **not** mean a check failed — most often it means required checks are still **pending**. Before diagnosing a PR as blocked by a specific tool, compare the failing check against the branch's *required* set. A red **non-required** check never blocks merge.

Real case (2026-07-18): two bump PRs showed `mergeStateStatus: BLOCKED` with `copilot-pull-request-reviewer` at `conclusion: failure` — the failure body was *"Copilot was unable to review this pull request because the user who requested the review has reached their quota limit."* That check was **not** in `required_status_checks`, so both PRs auto-merged the moment the required set (Skill Validation, composer-audit, gitleaks, DCO, …) went green. Reporting them as "Copilot-blocked" was wrong.

```bash
# The required set (the ONLY checks that can BLOCK):
gh api repos/OWNER/REPO/branches/main/protection \
--jq '.required_status_checks.contexts'

# A failing check NOT in that list is advisory — it does not gate merge.
# BLOCKED + all required checks green/pending → wait, don't intervene.
```

Corollary: a quota-exhausted Copilot review returns `conclusion: failure`, not `neutral` — treat "failure" on an advisory reviewer check as noise, not a code problem. Never reach for `--admin` to "unblock" it.

## Merge Queue Behavior and Pitfalls

### Sequential Processing
Expand Down
Loading