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

[don-petry]

Findings: measuring the PR thrash this proposal targets
I pulled the repo's recent PR and merge history to test how much of the serialization pain described above we're actually paying today. Short version: the thrash is real and we're already past the throughput threshold this proposal sets for "consider Merge Queue." The decision now hinges on two facts (plan tier + conflict-rate), not on whether the problem exists.

1. Throughput is already in Merge Queue territory
   94 PRs merged in the last ~7.7 days → ~12.3 merges/day.
   Daily counts: 06-07: 8 · 06-08: 16 · 06-09: 9 · 06-10: 21 · 06-11: 7 · 06-12: 5 · 06-13: 12 · 06-14: 16.
   The recommendation above says "consider Merge Queue when PR throughput grows to 10+ per day." Our median day is 10.5 and peaks hit 16–21. We're not approaching that threshold — we're consistently above it.
2. The fan-out is observable right now
   Auto-rebase updates every behind non-Dependabot PR on every push to main. Looking at the currently-open PRs:
   13 of 14 open PRs sit on the exact same base SHA (0c069f3, current main). The lone exception (feat: implement issue #143 — Compliance: secret_scanning_non_provider_patterns #518) is one merge behind. That means a recent merge cascade just branch-updated ~13 PRs at once.
   Their updated_at timestamps cluster within a ~20-minute window immediately after the latest merges — the signature of a fan-out, not organic activity.
   Several of these PRs have been open for days (feat: implement issue #431 — [Fleet Monitor] petry-projects/.github-private — pr-review-mention.yml #479 since 06-08, feat: implement issue #143 — Compliance: secret_scanning_non_provider_patterns #518 since 06-09, feat: implement issue #547 — Compliance: secret_scan_ci_job_present #550 since 06-10, feat: implement issue #382 — Enhance dev-lead and pr-review engines for Gemini 3.5 models #580/feat: implement issue #588 — [E2E] Scenario 04: dev-lead label routing test #589 since 06-11), so they've ridden through dozens of these rebase cycles.
3. Quantifying the wasted CI
   By Little's law (arrival ≈ 12.3/day × mean PR lifetime ≈ 34.7h) the repo carries ~14–18 open PRs concurrently.
   Every merge fans an update-branch out to all of them → a fresh CI run each. At ~12 merges/day that's roughly 170–220 auto-triggered branch-update CI runs per day.
   Merges land on average every ~2h during active periods. Any PR not at the very front of the review queue is re-staled before a human looks at it, so the overwhelming majority of those 170–220 daily CI runs are immediately invalidated — that is the thrash, in concrete numbers.
4. Latency tail confirms back-of-queue starvation
   Time-to-merge: median 5h, but mean 31h, p90 71h, max 629h (~26 days).
   26 of the last 100 PRs stayed open >24h; 11 stayed open >72h.
   That long tail is exactly the "PR keeps falling behind, gets rebased, re-runs CI, waits again" loop. Batching (Merge Queue testing the merge_group) collapses it because a passing batch merges atomically without per-PR re-checks.
   So, to what extent would we benefit?
   Materially — the scaling argument in the proposal is already met, not hypothetical. We are paying both costs the proposal names: high redundant CI volume from fan-out, and a heavy latency tail from serialization. Merge Queue's batching + "merge_group is the final arbiter" model directly targets both.

Agentic-conflict-resolution frequency. The unique feature we'd give up is the sentinel → dev-lead rebase path. I could not get a precise count: the trigger is an HTML-comment sentinel () that GitHub search doesn't index reliably. Most dev-lead PRs touch disjoint files (different issues), so hard conflicts are probably a minority — but the compliance / fleet-monitor PRs that all edit shared workflow files are the conflict-prone cluster. Worth instrumenting the sentinel with a counter before deciding how much we'd lose.

Recommendation
Pursue the hybrid the proposal sketches — Merge Queue for the merge-time guarantee + batching, auto-rebase retained only as the agentic conflict-resolution fallback. The throughput data justifies it.

Regardless of plan / as an immediate, free mitigation: stop fanning out to all behind PRs. Restrict auto-rebase to PRs that are approved / review-ready (or just the oldest N at the front of the queue). Rebasing a PR that won't be looked at for two days only to re-stale it minutes later is pure waste — this single change would cut the bulk of the ~170–220 daily redundant CI runs without any plan upgrade or loss of the agentic fallback.
Method note: figures derived from the last 100 closed PRs (94 merged, 06-07→06-14) and the 14 currently-open PRs via the GitHub API.

Workflow-run timing was excluded — the runs endpoint returned an unfiltered firehose in this environment, so per-workflow CI durations weren't trustworthy; CI-run counts above are modeled from merge rate × concurrency, not scraped.

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #736 — Cut auto-rebase fan-out thrash: restrict to review-ready PRs + instrument the agentic-conflict-resolution rate

3 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Instrument auto-rebase: agentic-conflict-resolution rate + fan-out CI-run volume report #737 (M) — [Phase 1] Instrument auto-rebase: agentic-conflict-resolution rate + fan-out CI-run volume report
• [Phase 1] Restrict auto-rebase fan-out to review-ready PRs (free, plan-independent mitigation) #738 (M) — [Phase 1] Restrict auto-rebase fan-out to review-ready PRs (free, plan-independent mitigation)
• [Phase 2] Validate the reduction and record the Merge Queue go/no-go decision #739 (S) — [Phase 2] Validate the reduction and record the Merge Queue go/no-go decision

Open questions for review:

• Merge Queue adoption (the plan-gated follow-on) requires a GitHub Team or Enterprise plan for private repos and would trade away the agentic conflict-resolution path and proactive background branch updates. Is petry-projects on a qualifying plan, and is leadership willing to make that trade? This gates the follow-on only, not this epic.
• Does the dev-lead automation have write access to petry-projects/.github to implement the auto-rebase-reusable change (Story 2), or must a human maintainer open that cross-repo PR? Story 2 is marked hands_off pending this.
• Exact review-ready eligibility predicate for the fan-out restriction: approved reviews only, an explicit review-ready label, or the oldest N PRs at the front of the queue? Story 2 ships a sensible default but the precise rule should be confirmed.
• The currently-open PRs referenced in the discussion (feat: implement issue #431 — [Fleet Monitor] petry-projects/.github-private — pr-review-mention.yml #479, feat: implement issue #143 — Compliance: secret_scanning_non_provider_patterns #518, feat: implement issue #547 — Compliance: secret_scan_ci_job_present #550, feat: implement issue #382 — Enhance dev-lead and pr-review engines for Gemini 3.5 models #580, feat: implement issue #588 — [E2E] Scenario 04: dev-lead label routing test #589) are evidence of the fan-out thrash, not prerequisites — they are intentionally not modeled as blocking edges.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #736 to hand it to initiative-driver for auto-implementation.

[don-petry]

We are on a public GitHub repo, so all features are supported.

Leadership accepts tradeoff of merge queues.

Initial scope is just .github-private. Additional scope is org standard and rollout to fleet repos.

[github-actions[bot]]

Enhancement: Auto-Rebase vs. Merge Queue — Decision Criteria & Migration Path

Sharpened problem & goal
The discussion frames this as a comparison, but the actionable question is: under what conditions should petry-projects migrate to GitHub's Merge Queue, and what is the concrete migration plan? A comparison without a decision criterion is hard to act on. Key ambiguity: the org uses auto-rebase across multiple repos with varying PR volumes — the answer may differ per repo.

Context
This repo has substantial auto-rebase infrastructure that any migration must account for:

• auto-rebase.yml (thin caller) + central auto-rebase-reusable.yml — handles non-Dependabot PRs
• auto-rebase-retry.yml — workflow_run failure-handler that self-heals failed auto-rebase runs (documented AGENTS.md exception)
• auto-rebase-health.yml — daily + workflow_dispatch report quantifying conflict-resolution rate and CI fan-out; this is the key data source for the migration decision — it already collects exactly what's needed

The health report data drives the break-even analysis: at what PR-merge-per-day volume does Merge Queue's batched CI outperform the current per-PR fan-out cost? GitHub Merge Queue and auto-rebase solve adjacent problems (Merge Queue serializes merging; auto-rebase keeps open PRs current) — the org may want both running simultaneously. This distinction is worth making explicit.

Impact / Effort

• Impact: MEDIUM — auto-rebase works and has retry self-healing; Merge Queue would reduce CI fan-out at scale but the reliability benefit is incremental given auto-rebase-retry.yml
• Effort: M — decision + pilot in one repo is M; org-wide migration with reusable workflow updates is L

Suggested acceptance criteria

• auto-rebase-health.yml report is extended to output PR-merge throughput (merges/day per repo) — the key input to the Merge Queue break-even analysis
• A written decision record (docs/decisions/merge-queue-adr.md) documents: the break-even volume threshold, which repos (if any) should migrate first, and the rollback plan
• The decision record explicitly addresses whether Merge Queue replaces or complements auto-rebase (they solve different phases of the merge lifecycle)
• A proof-of-concept Merge Queue integration is piloted in one low-risk repo with a merge_group required check, measuring CI fan-out reduction over 2 weeks
• The org-level auto-rebase-reusable.yml is NOT modified until the pilot completes — thin-caller stubs make this safe to scope independently