Designing a Required-Check Contract for Matrix CI and Merge Queues

A smaller contract is one unfiltered workflow with a single uniquely named reporting job, while the matrix remains non-required diagnostic coverage. The reporting name must also be reserved: do not emit a commit status with that same name, because a same-named check run and commit status would both have to pass if required. Validate the required result against the applicable SHA—not merely the displayed label.

on: [pull_request, merge_group]

jobs:
  test:
    strategy:
      matrix: ...
    # matrix coverage

  required-contract:
    name: required-contract
    if: ${{ always() }}
    needs: [test]
    # explicitly fail or succeed from the declared matrix policy

The essential implementation decision is not always() itself. It only ensures the reporting job runs after its prerequisite finishes even when that prerequisite failed or was skipped. The reporting job must then encode the repository rule: for example, whether any matrix failure fails required-contract, and how a skipped or cancelled matrix result is treated. Without that explicit branch, a stable required name can mask an undefined failure policy.

• Keep this workflow free of path, branch, and commit-message filters so the contract result is emitted rather than left Pending.
• Require only required-contract; leave matrix job names unrequired and variable.
• Run the same contract path for pull_request and merge_group, then verify its conclusion on the applicable SHA after a new commit and after queue entry.
• Record that no commit status may use required-contract, alongside the applicable-SHA validation case.

This loses the ability to make each matrix coordinate independently merge-blocking, but it yields one bounded required surface and makes that loss an explicit policy choice. GitHub documents both the collision rule and the distinction between workflow filtering (Pending) and conditionally skipped jobs (Success); it also documents always() for a dependent job that must run after a failed or skipped prerequisite. Required-status-check troubleshooting Using jobs in workflows

An adapter job is useful only if it separates execution eligibility from merge verdict. if: ${{ always() }} supplies the former: it ensures the adapter is scheduled after its declared needs finish, even when one failed or was skipped. It must not implicitly turn those upstream outcomes into a passing required result. GitHub documents that ordinary needs skip downstream jobs after a failed or skipped prerequisite, while always() overrides that propagation for execution.

jobs:
  merge_contract:
    name: merge-contract
    needs: [test_linux, test_windows]
    if: ${{ always() }}
    # verdict logic must inspect every declared prerequisite
    # fail: failure or cancellation
    # explicit policy: skipped
    # pass: only the declared acceptable result set

Make the adapter’s interface explicit: its inputs are the fixed prerequisite set and each terminal conclusion; its output is one stable check name with a defined verdict table. In particular, classify skipped rather than inheriting the platform’s acceptance of a skipped required check: either reject it because that matrix coordinate is mandatory, or accept it only where the contract records why absence of that coordinate is valid. Treat cancellation as a separately specified non-success outcome unless the repository deliberately establishes otherwise.

The verification case should therefore force one prerequisite to fail, one to skip, and separately one to cancel; confirm that the adapter runs in all three cases but emits the specified failure verdict for each. Then repeat on the applicable latest SHA and on merge_group if the adapter is required by a merge queue. This preserves a single reporting boundary without silently weakening the matrix failure signal. The required-check guidance specifically recommends always() with needs for a required check that depends on other jobs, and also notes that skipped required checks are successful, so execution and verdict need distinct tests.

GitHub Actions: Using jobs in a workflow · GitHub: Troubleshooting required status checks

The transition to a new required-check contract needs its own failure-and-recovery test. A successful pull-request run is not sufficient evidence that a replacement aggregate, filter exception, or queue trigger protects the same decision point.

• Before changing the requirement, record the old and proposed check identities, reporting event, and applicable SHA for each path. If the aggregate replaces matrix requirements, inject one failed prerequisite and one skipped prerequisite. Its job should run after dependencies complete only where that is intentional—for example with if: ${{ always() }}—and must then fail unless the recorded dependency results exactly meet policy. GitHub documents that always() permits a dependent job to run after failed or skipped prerequisites; it does not make that job’s success a valid failure signal.
• Exercise a change that misses each relevant path, branch, or commit-message filter. Record whether a workflow run exists for the applicable SHA and the required-job conclusion when it does. A filtered workflow leaves its associated check pending and blocks a required merge, whereas a conditionally skipped job reports success; these are different degraded states and need separate recovery actions. The workflow syntax documentation describes the pending result from workflow-level filtering.
• Repeat the failed, skipped, and filtered cases through the merge queue, recording the queue commit SHA, merge_group event, and exact reported check identity. Required Actions checks for a merge queue need that separate event, and required checks must pass on the latest applicable SHA. GitHub’s required-check guidance documents both constraints.

Keep the prior protection contract as the rollback path until each injected failure blocks both paths, each valid case progresses, and a deliberately filtered case produces the expected detectable state. If the new result is absent, pending unexpectedly, or attached to a different SHA, restore the prior requirement rather than treating a similarly named pull-request success as recovery.