GitHub merge queue: why required checks never report

If you enable GitHub's merge queue and your required checks run only on pull_request, merges will fail because the check never reports on the queue's temporary branch. Add the merge_group event to every workflow that provides a required check. Then the checks run against the real post merge state.

What a merge queue does

GitHub's documentation describes it as a way to merge pull requests into a busy branch without breaking it with incompatible changes. It merges queued pull requests in order, and checks that required status checks pass against the latest target branch plus the changes ahead in the queue.

A pull request is removed if it fails required checks, times out or conflicts with the base.

This matters for security gates. A scan that passed on a stale branch may say nothing about the code that actually lands.

The gotcha

The documentation is direct: you must use the merge_group event to trigger your GitHub Actions workflow when a pull request is added to a merge queue. The event is separate from pull_request and push. Without it, the merge fails because the required status check is not reported.

Fix:

on:
  pull_request:
  merge_group:

Third party CI

For CI systems outside Actions, GitHub says to run the pipeline on pushes to branches that begin with gh-readonly-queue/ followed by the base branch name. Otherwise the same missing check problem appears.

Do not run everything twice

Cheap checks like linting can run on pull_request only if you do not mark them required. But anything required must report on both events. For expensive scans, consider whether the queue run is enough and the pull request run can be a lighter preview. That is a cost choice, not a security one. The required check must report in the queue.

Security gate placement

A good pattern:

1. On pull_request, run fast feedback: tests, lint, dependency check.
2. On merge_group, run the full required gate: tests plus the security scan.
3. Make the gate job name identical in both triggers, since branch rules match by check name.

This way developers get quick answers, and the code that merges is the code that was checked.

Merge method and history

Queued pull requests can be merged using merge, rebase or squash, chosen in the queue settings. The page I fetched did not state which plans include merge queues, so check your repository settings.

Checklist before enabling

• Every required workflow lists merge_group.
• Required check names are unique and stable.
• Third party CI watches the queue branch prefix.
• Timeouts are generous enough for the full gate.
• You have a plan for flaky tests, since a flaky failure ejects the pull request.

See also branch protection versus rulesets for where the required check is configured.

Safeguard policies and gates can serve as the security check in this flow. The free scan is at gold.safeguard.sh/scan.

Quick check

Sources

• Managing a merge queue

Last reviewed: 19 October 2026.