Rulesets docs don't disclose that bypass_actors is not honored by auto-merge completion

Open Beginner friendly
#45,265 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
github
Domain
documentation

Research direction

Start with the two affected Rulesets pages: “Creating rulesets for a repository” and “Available rules for rulesets,” especially the bypass list and pull request rule sections. Review the reported auto-merge behavior and add a clear limitation note covering bypass_actors and auto-merge completion, with the direct merge endpoint distinction documented; the issue is done when both relevant pages accurately explain this behavior.

Written by the indexing model from the issue text.

Description

content needs SME never-stale repositories Waiting on SME review
Page(s) affected
What's wrong

The Rulesets documentation describes bypass_actors (a Team, Role, GitHub App/Integration, etc. added to a ruleset's bypass list) as being able to bypass a rule such as "Require a pull request before merging" / "Require review from Code Owners". It does not document an important limitation we've confirmed by testing: the bypass grant is only honored by a synchronous, direct merge call — it is not consulted by GitHub's async auto-merge completion process (gh pr merge --auto, enablePullRequestAutoMerge, or the "Merge when ready" UI button).

Repro / evidence
  • Ruleset: pull_request rule, require_code_owner_review: true, required_approving_review_count: 1, with a GitHub App added to bypass_actors (Integration type; tested both bypass_mode: "always" and "pull_request").
  • A PR approved by the bypass-listed actor with auto-merge enabled (gh pr merge --auto --squash) stayed mergeStateStatus: BLOCKED / reviewDecision: REVIEW_REQUIRED indefinitely — confirmed via a clean 10-minute poll (every 20s, 30/30 polls) with a fresh trigger event and zero manual intervention.
  • The same PR, same bypass-eligible actor, merged instantly when calling the merge endpoint directly instead: 
    gh api repos/OWNER/REPO/pulls/N/merge -X PUT -f merge_method=squash

So the bypass mechanism works, but only for one of the two documented ways to merge a PR, and the docs don't call this out anywhere.

What we'd like to see

A note on the bypass_actors / rules pages clarifying that bypass grants are not currently honored by auto-merge completion, and that automation relying on bypass should call the merge endpoint directly rather than enabling auto-merge, until/unless this is fixed at the platform level.

Related reports (same underlying platform behavior, not a docs-only issue)
Dominant language
TypeScript
Stars
20.9k
Forks
68.8k
Avg merge
15h 4m
Merged PRs (30d)
103

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/docs

All issues in github/docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.