Table of contents

• Why merge queues matter
• Reducing contention
• Making reviews more efficient
• Automating merges
• Maintaining velocity and quality
• Choosing and using tools
• Conclusion

Managing a merge queue is essential for keeping the main branch stable in a busy GitHub repository. It can boost development speed while catching potential issues before they hit production. This post outlines best practices to reduce contention, streamline reviews, and automate merges—while preserving code quality. We also highlight how tools like Graphite, GitHub's native merge queue, and others can help. If you're new to the concept, see What is a merge queue?.

Why merge queues matter

In busy projects, direct merges can break builds due to subtle, non-conflicting changes. For example, if one PR modifies a function signature and another PR relies on the old version, merging both without testing together can break production. GitHub’s “require branches to be up to date” setting helps, but developers often get stuck rebasing.

Merge queues solve this by rebasing PRs onto the latest main branch and running tests on a temporary merge branch. Only if all checks pass does the PR merge. This avoids the "rebase race" while keeping the trunk stable.

Reducing contention

To avoid long queues:

• Favor small PRs. Small, focused changes reduce merge conflicts and review time.
• Batch PRs. Queues that test multiple PRs together (batching) can increase throughput. Graphite and GitHub support this.
• Allow parallelism. Instead of strict FIFO, run CI on multiple PRs at once. GitHub lets you adjust concurrency.
• Prioritize urgent PRs. Use labels or dedicated queues to allow hotfixes to skip ahead.
• Skip failed PRs. Automatically remove PRs that fail CI to avoid blocking others.

Graphite's merge queue supports batching, stack-aware processing, and parallel CI, which can reduce pipeline wait time dramatically.

Making reviews more efficient

PRs shouldn’t sit idle waiting for review:

• Break down work. Stacked PRs are easier to review and merge faster.
• Define criteria. Standardize rules like "2 approvals + passing checks" before merge.
• Assign reviewers. Use tools like CODEOWNERS and auto-assign bots.
• Use dashboards. Graphite’s Pull Request Inbox and Slack integrations keep teams aware of pending reviews.
• Encourage quick reviews. Build team habits and expectations around timely feedback.

Clear criteria, automation, and visibility reduce delays in reviews, keeping the queue moving.

Automating merges

Merge queues depend on automation:

• Use auto-merge. GitHub can merge PRs when checks pass, even outside work hours.
• Trigger on labels or comments. Bots can listen for signals like “ready-to-merge” to queue PRs.
• Configure CI for queue events. GitHub’s merge_group event triggers queue-based CI runs.
• Choose merge methods. Use squash for a cleaner history, or rebase/merge if more detail is needed.

Tools like Mergify offer advanced rule sets, while Graphite provides stack-aware and parallel merge features.

Maintaining velocity and quality

Merge queues should not compromise quality:

• Enforce gates. Require tests, linters, and reviews before merge.
• Keep CI fast. Long pipelines reduce queue throughput. Optimize with caching and parallelism.
• Fix flaky tests. Flaky CI results cause unnecessary queue delays.
• Monitor metrics. Track time-in-queue, failure rates, and throughput.

A stable queue, backed by reliable tests and fast CI, keeps code flowing without regressions. Graphite and GitHub both support pause/resume features and batch rollback if issues occur.

Choosing and using tools

Start with GitHub Enterprise Cloud if you're already using it or working with public repos. It supports up-to-date protection, parallel merging, and queue branches. For more flexibility:

• Graphite supports stacked PRs, parallel CI, batching, and dashboards.
• Mergify offers flexible, rule-based merge triggers.

Whichever tool you choose, integrate it with your CI, test on a trial branch, and educate your team. Merge queues are most effective when paired with solid engineering habits.

Conclusion

Merge queues help teams ship faster and safer by enforcing checks, automating rebases, and keeping the main branch green. Focus on reducing queue contention, streamlining reviews, and automating intelligently. Tools like Graphite and GitHub’s native queue make these strategies practical—and scalable—for any engineering team. For further reading, check out Merge queue best practices.