Table of contents

• What is a merge queue?
• Why use a merge queue?
• How to set up GitHub's merge queue
• Graphite: An automated, stack-aware alternative
• GitHub vs. Graphite: Which should you use?
• Conclusion

What is a merge queue?

A merge queue is an automated tool that manages the merging of pull requests (PRs) into your main branch. Instead of merging directly, pull requests are placed into a queue. Each queued PR is then combined with the current main branch state and other queued PRs into temporary merge branches. Continuous Integration (CI) checks run against these combined branches. Only PRs passing these checks are automatically merged, ensuring the main branch remains stable and continuously deployable.

Why use a merge queue?

Merge queues offer several advantages:

• Prevent merge conflicts and broken builds by verifying combined changes beforehand.
• Reduce manual rebasing and rerunning tests, saving developers' time.
• Streamline deployments by ensuring only passing builds reach production.

How to set up GitHub's merge queue

Follow these steps to set up a merge queue on GitHub:

Step 1: Configure branch protection

• Go to your GitHub repository and navigate to Settings → Branches.
• Create or edit the branch protection rule for your main branch.
• Enable Require status checks to pass before merging.
• Enable Require merge queue and configure the merge method (merge, squash, or rebase).

Step 2: Update CI workflows

Your GitHub Actions workflows must handle both pull_request and merge_group events:

on:
  pull_request:
  merge_group:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm test

For other CI providers, ensure workflows trigger on branches with the prefix gh-readonly-queue/{base_branch}.

Step 3: Using the merge queue

Once checks pass, click Merge when ready on your PR, or use the CLI:

gh pr merge

GitHub automatically places the PR into the merge queue.

Step 4: Monitoring and managing your merge queue

You can:

• View your merge queue status via the Branches page or directly from PR pages.
• Remove a PR from the queue if necessary.
• Prioritize a PR by moving it to the top, triggering a new combined build.

Graphite: An automated, stack-aware alternative

Graphite offers advanced, automated merge queue capabilities that complement GitHub with additional benefits like stack awareness, fast-forward merges, and intelligent batching for CI checks.

Key advantages of Graphite:

• Stack-awareness: Automatically rebases and merges dependent PRs.
• Batching & parallel CI: Saves time and reduces CI costs.
• Hot-fix support: Easily push critical changes to the front of the queue.
• User-friendly UI: Offers intuitive controls within GitHub and Graphite.

Setting up Graphite's merge queue:

1. Install and authorize the Graphite GitHub app.
2. Disable GitHub's native merge queue in your repo settings.
3. Enable Graphite's merge queue via Graphite's repo settings, selecting your desired merge strategy (fast-forward, squash, or rebase).

Using Graphite's merge queue:

• Add PRs via Graphite's UI or by using GitHub labels.
• Monitor and manage your queue through Graphite's intuitive dashboard, easily pausing, reprioritizing, or removing PRs.

GitHub vs. Graphite: Which should you use?

• GitHub Merge Queue: Simple setup, ideal for smaller teams or projects.
• Graphite Merge Queue: Ideal for teams needing advanced automation, stack-based workflows, or heavy CI optimizations.

Conclusion

Implementing a merge queue dramatically improves your repository's stability and developer productivity. Whether you choose GitHub's built-in merge queue for simplicity or Graphite for greater automation, adopting this approach is a significant step toward smoother, more reliable deployments.