GitHub Merge Queues

GitHub merge groups are used for testing multiple pull requests together before merging. This is particularly useful for repositories that use merge queues to maintain a linear history.

To trigger a run on a merge group event, you can use a push trigger with the following snippet, which leverages the special branch prefix GitHub provides for merge groups.

on:
  github:
    push:
      - if: ${{ starts-with(event.git.branch, 'gh-readonly-queue/') }}
        init:
          commit-sha: ${{ event.git.sha }}

Required Status Checks

If the same RWX config produces PR checks via the pull_request trigger and merge queue checks via the push trigger, GitHub treats them as two distinct status checks. That's because RWX includes the trigger type in the default check name — for example, RWX: ci.yml (pull request) and RWX: ci.yml (push). Marking one as required in branch protection leaves the other unsatisfied in the opposite context, which blocks the merge queue.

Set an explicit status check name on both triggers so they report under the same name.

on:
  github:
    pull_request:
      status-checks:
        name: CI
    push:
      - if: ${{ starts-with(event.git.branch, 'gh-readonly-queue/') }}
        status-checks:
          name: CI

Both triggers will now report RWX: CI, and a single RWX: CI required check in branch protection covers both PR and merge queue contexts.

Concurrency Pools

If your config uses concurrency pools, avoid applying a pool with on-overflow: cancel-running to merge queue runs. Cancelling an in-flight merge queue check when the next one starts will leave the queue waiting on a cancelled result, which generally isn't what you want.

In fact, you may not want to use a concurrency pool at all for merge queue runs, since each run will check out the branch with the upstream changes already applied, meaning they can run safely in parallel.

When a single config handles both regular pushes and merge queue pushes, you can use if to conditionally opt out of a pool for merge queue runs.

on:
  github:
    push:
      init:
        branch: ${{ event.git.branch }}
        commit-sha: ${{ event.git.sha }}

concurrency-pools:
  - id: your-org/your-repo:branch-${{ init.branch }}
    if: ${{ init.branch !~ '^gh-readonly-queue/' }}
    capacity: 1
    on-overflow: cancel-running