Git merge queues and required checks: test the integration candidate

TL;DR: A merge queue validates the candidate formed from the current base and queued changes before admitting it to the protected branch. Required checks must run on that candidate revision; a green result on an earlier pull-request head is different evidence.

Two independently green changes can conflict

Suppose the base branch exposes a function accepting milliseconds. Pull request A renames it and updates existing callers. Pull request B adds a new caller using the original name. Each can pass against the old base while their combined result fails to compile.

Requiring contributors to update their branches helps, but high merge traffic can invalidate a result while it waits for approval. A queue serializes or groups integration decisions and tests the relevant combined candidate. GitHub's merge-queue documentation describes how its candidates incorporate the latest base and changes ahead in the queue.

The mechanism protects a specific invariant: the evidence used to merge should describe the code being integrated. It does not prove the tests cover all production behavior.

If an earlier queued change is removed, later candidates may need rebuilding because their combined code changed. Read the queue's current candidate identifier before diagnosing an apparently repeated build.

Trigger CI for the merge-group event

For GitHub Actions, a workflow supplying a required check needs to handle the queue's merge_group event as well as the pull-request event where appropriate. For a Node.js repository with a committed npm lockfile and typecheck and Vitest test scripts, the following workflow tests the event's checked-out revision. Adapt the working directory and commands to the repository.

name: integration-check
"on":
  pull_request:
  merge_group:
permissions:
  contents: read
jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: '24'
      - run: npm ci
      - run: npm run typecheck
      - run: npm test -- --run

The checkout action defaults to the event's reference or SHA; avoid overriding it with a pull-request head in the queue run. The Node setup action supplies the requested runtime. Major tags keep this example readable; use reviewed immutable action revisions in a production workflow. Keep the required check name stable and configure branch rules to require the intended job.

The quotation around on also avoids YAML 1.1 tools interpreting that key as a boolean during external parsing. GitHub Actions understands the event key itself.

Match evidence to revision and event

External CI needs the same revision discipline even if it uses different event handling. Record the tested commit with the artifact and result. A result attached to the correct PR number but wrong commit is insufficient.

Be cautious with path-based conditions. If a branch rule expects a check and the workflow skips the event entirely, the required result may never arrive. Decide how the repository provides an explicit, truthful result for changes that do not require the full test suite.

Treat queue throughput as a capacity problem

Imagine each integration candidate takes ten minutes to test. A serial queue that validates one independent change per run can complete at most about six such runs per hour before overhead. If changes arrive faster, waiting time grows. This is illustrative capacity arithmetic, not a GitHub service limit.

Parallel candidate construction can improve throughput, but failed earlier candidates may invalidate later work. Distinguish build concurrency from merge grouping and merge limits; they are separate settings with different effects. Optimize the expensive checks and reduce flaky failures before weakening the protected-branch requirement.

Keep deployment separate from candidate testing. A temporary integration candidate should not publish to production merely because its workflow resembles the main-branch build. CI/CD architecture explains how test evidence and release authorization connect.

Check what the green badge proves

Self-check: A and B each passed their PR checks. Candidate A plus B failed a compilation check. Can B merge because its author did not edit the file named in the error?

No. The candidate failed the integration contract, regardless of which file B directly changed. Investigate the combined diff and fix or remove the incompatible change. Then obtain fresh evidence for the recomputed candidate rather than reusing the earlier PR result.