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

[jgsuess]

Page(s) affected

• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository
• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets (bypass list / pull request rule sections)

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)

• https://github.com/orgs/community/discussions/162623
• https://github.com/orgs/community/discussions/190610
• https://github.com/orgs/community/discussions/113172
• https://github.com/orgs/community/discussions/167357
• https://github.com/orgs/community/discussions/136531
• gh pr merge refuses when ruleset bypass authority would resolve the block cli/cli#13388
• gh pr merge doesn't exempt actor from rule. cli/cli#13458

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[Sharra-writes]

@jgsuess Thanks for the issue! I'm asking the repositories team about this to make sure it's not a bug and is intended, and we'll let you know what we hear.

[github-actions]

This is a gentle reminder for the Technical Content team that this issue is waiting for technical review by a subject matter expert (SME).