Merge queue checks: test the combined commit that will land

Last updated: 5 Oct 20266 min read

tutorial

A merge queue constructs a candidate revision containing one or more accepted changes and the current base branch. Checks on each pull-request head do not prove that combined candidate works. A required workflow must run on the queue event and report against that candidate; otherwise the queue may wait for a result that never appears, or a team may weaken the gate to work around it.

Operational decision

A receipt service and ledger library change pass separately, but their combined dependency graph breaks an integration test. Configure the required verification workflow to run for pull requests and merge groups. The fragment shows the event contract; the referenced script must build and test the checked-out revision, not fetch an earlier head. Log the revision, event type, dependency lock digest, and final artifact digest in the result. Submit two compatible-looking changes together and deliberately make their combination fail in a test repository; confirm the queue rejects the group while preserving each pull request for repair. Repeat after the base branch advances. If an external CI system reports the check, confirm it attaches the conclusion to the queue revision and has a stable check identity. Deploy only an artifact built from the accepted candidate or its resulting merge commit.

name: receipt-merge-verification
on:
  pull_request:
  merge_group:
    types: [checks_requested]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./ci/verify-receipt.sh

Cost and verification

A fresh combined build consumes CI capacity and adds queue latency, especially when several pull requests are grouped. That cost buys evidence about the revision that will actually enter the protected branch. Measure queue wait, group failure rate, reruns after base movement, and the gap between checked revision and released artifact. A green check with a mismatched revision is worse than a visible red check because it can authorize untested bytes.

Common Mistakes

Do not use only pull-request-head checks as proof that a merge group passes.
Do not turn off a required check because its queue event is missing.
Do not release an artifact from a different revision than the accepted candidate.

Connected lessons

Practice and check

devops

operations