How to Enable the GitHub Merge Queue

The merge queue is enabled per branch through a branch protection rule or ruleset, then activated by requiring it before merging.

Enable the merge queue on the target branch in branch protection (or a ruleset), then add the merge_group trigger to the workflow that produces your required checks so those checks run against the queued merge candidate.

Steps

• Open Settings to Branches (or Settings to Rules) and edit the rule for the default branch.
• Enable "Require merge queue" and set the grouping and batching limits.
• Keep "Require status checks to pass" on and list the checks the queue must satisfy.
• Add on: merge_group to the workflow that runs those checks.

Enable the queue

Settings > Branches > Branch protection rule (main)
  [x] Require merge queue
      Merge method:            Squash
      Build concurrency:       5
      Minimum group size:      1
      Maximum group size:      5
      Wait time to build:      5 minutes

Wire the workflow to the queue

on:
  merge_group:
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Gotchas

• A required check that never runs on merge_group leaves the queue entry stuck pending; see the stuck "expected" check guide.
• Only repositories with branch protection or rulesets can require the queue; forks and unprotected branches cannot.

Related guides