Auto-Rebase Workflow vs. GitHub Merge Queue

[don-petry]

Auto-Rebase Workflow vs. GitHub Merge Queue

Overview

This discussion compares your current custom auto-rebase workflow (implemented in .github/workflows/auto-rebase-reusable.yml and dependabot-rebase-reusable.yml) with GitHub's native Merge Queue feature, which became generally available in 2024.

Both solve the same fundamental problem: branch protection's "Require branches to be up to date" creates a serialization bottleneck where merging any PR makes every other open PR fall behind until manually updated and re-checked by CI.

How Each Works

Your auto-rebase workflow (triggered on every push to main):

• Finds all behind non-Dependabot same-repo PRs
• Calls PUT /pulls/{n}/update-branch with merge method
• Merges main into each PR branch, keeping them current
• CI re-runs on the updated branches
• On conflict, dev-lead agent attempts agentic rebase

GitHub Merge Queue (when PR added to queue):

• Creates a temporary merge_group branch: base + all PRs ahead in queue + this PR
• Runs CI on that synthetic merged state
• On success: commits merge to main
• On failure: ejects PR and notifies author

Side-by-Side Comparison

Dimension	Your auto-rebase	GitHub Merge Queue
Trigger	After every merge to main	When PR added to queue
What CI tests	PR branch rebased onto current main	Synthetic merge_group (final merged result)
Race window	Exists — gap between "CI passed" and "PR merges"	Eliminated — CI tests actual merged result
Throughput	Serial: one-at-a-time	Batching: multiple PRs tested together
Conflict handling	Sentinel comment → dev-lead agentic rebase	Ejects PR, author resolves manually
Fork PRs	Skipped (can't push to fork branches)	Works — merge_group in base repo
Dependabot	Separate workflow with GitHub App token	Joins queue like any PR
Approval invalidation	Avoided by using merge method	PR branch untouched
Plan requirement	Free (all plans)	Private repos require Team or Enterprise
CI changes needed	No	Yes — add merge_group trigger
Agentic conflict resolution	Yes (unique feature)	No — manual resolution only
Customizability	Full control (you own the logic)	Opaque system, limited options

Key Architectural Difference

Auto-rebase keeps branches recent. It checks "will this branch pass CI on current main?" — leaving a race window between "CI passed" and "PR merges" where another PR could land and change main again.

Merge Queue eliminates the race. It checks "does this branch become main?" by testing the actual merge_group. Under strict branch protection, the queue is the final arbiter — if CI passes on merge_group, the PR is guaranteed to merge without re-checking.

This is why Merge Queue scales: it batches PRs and tests them as one unit. If 5 PRs pass together as merge_group, all 5 merge atomically in order.

What You'd Lose by Switching

1. Agentic conflict resolution — dev-lead attempting auto-rebase on conflict (422) is unique to your system. Merge Queue ejects and notifies.
2. Free-plan private repo support — Merge Queue requires Team or Enterprise for private repos.
3. Automatic background updates — Merge Queue doesn't keep branches proactively up-to-date; it only acts when a PR joins the queue.

What You'd Gain

1. No CI races — strict up-to-date checking is satisfied by the merge_group test itself.
2. Batched throughput — multiple PRs tested and merged together.
3. Fork PR support — currently excluded from auto-rebase.
4. Simpler Dependabot flow — no need for GitHub App token workaround to bypass recursive-trigger guard.

Recommendation

Not mutually exclusive. For your current setup (small team, free-plan private repos, agentic conflict resolution as a differentiator), auto-rebase is well-suited.

When to consider Merge Queue:

• PR throughput grows to 10+ per day and CI takes >5 min each
• Team is on GitHub Team or Enterprise (private repo support)
• You're willing to lose agentic conflict resolution and background branch updates

Coexistence scenario: Merge Queue handles the merge-time guarantee; auto-rebase continues as background maintenance. This hybrid approach is viable but adds operational complexity.

References

• Managing a merge queue - GitHub Docs
• Merging a pull request with a merge queue - GitHub Docs
• GitHub merge queue is generally available - The GitHub Blog
• How GitHub uses merge queue to ship hundreds of changes every day - The GitHub Blog