How to Use the merge_group Trigger in GitHub Actions

The merge_group event fires when the queue creates a temporary branch combining the base and the queued pull requests, and your required checks must listen for it.

Add merge_group to the workflow on: list so the same checks run against gh-readonly-queue/<base>/.... Without it, the queue waits forever for a check that never starts.

Steps

Add merge_group: to the on: block of the workflow that emits required checks.
Keep pull_request: so PRs still get feedback before entering the queue.
Check github.event_name == 'merge_group' if a step should behave differently in the queue.

Workflow

.github/workflows/ci.yml

on:
  merge_group:
    types: [checks_requested]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run test:ci

Read the queue ref

Terminal

# github.ref on a merge_group run looks like:
refs/heads/gh-readonly-queue/main/pr-42-a1b2c3d

Gotchas

If a required check runs only on pull_request, the queue entry sits pending because that check is never requested for the merge group.
The merge_group ref is read-only; do not push to it from the workflow.