How to Set Up a Merge Queue for a Monorepo With GitHub Actions

A merge queue batches PRs and tests each against the up-to-date base, catching semantic conflicts a stale PR would miss.

Enable the merge queue in branch protection and add the merge_group trigger to your workflow so the required checks also run on queued batches.

Steps

• Enable Require merge queue in branch protection for the default branch.
• Add merge_group to the workflow on: triggers.
• Make the build/test job a required status check.

Workflow

on:
  pull_request:
  merge_group:
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm ci
      - run: npx turbo run lint test build --filter='...[origin/main]'

Gotchas

• If the workflow lacks merge_group, the required check never reports and the queue stalls.
• Affected filters in the queue should diff against the queue base, not the PR base.

Related guides