ci: collapse 5 required PR-time checks into a single Merge Gate verdict

[danielmeppiel]

Why

PR #865 shipped Merge Gate but only watching one check (Build & Test (Linux)). The 4 stub checks (Build (Linux), Smoke Test (Linux), Integration Tests (Linux), Release Validation (Linux)) remained separately required in branch protection. That's half the architecture.

This PR finishes the job: Merge Gate aggregates all PR-time required checks into a single verdict. Branch protection then only needs to require Merge Gate / gate. This is the Tide (Kubernetes) / bors pattern.

Before vs after

                BEFORE                                           AFTER
  +-----------------------------+               +-----------------------------+
  | Branch protection requires: |               | Branch protection requires: |
  |   Build & Test (Linux)      |               |   Merge Gate / gate         |
  |   Build (Linux)             |               +--------------+--------------+
  |   Smoke Test (Linux)        |                              | aggregates
  |   Integration Tests (Linux) |                              v
  |   Release Validation (Linux)|               +-----------------------------+
  |   Merge Gate / gate         |               | merge_gate_wait.sh polls:   |
  +-----------------------------+               |   Build & Test (Linux)      |
       6 required checks                        |   Build (Linux)             |
                                                |   Smoke Test (Linux)        |
                                                |   Integration Tests (Linux) |
                                                |   Release Validation (Linux)|
                                                +-----------------------------+
                                                       1 required check
                                                       5 informational checks

What changes

File	Change
merge_gate_wait.sh	EXPECTED_CHECK (single) -> EXPECTED_CHECKS (comma-separated list). Parallel indexed arrays for per-check state (no bash 4+ associative arrays required). Fail-fast on first failing check. Timeout categorizes missing vs stuck.
merge-gate.yml	Pass all 5 check names via EXPECTED_CHECKS env. Updated header comment to reflect single-authority model.
CHANGELOG.md	One line.

Why this is better

• Single source of truth. "Is this PR mergeable" = "is Merge Gate / gate green". One question, one answer.
• Decoupled. Adding a new required check = edit EXPECTED_CHECKS in merge-gate.yml. No ruleset edit, no admin permissions needed.
• Same recovery story everywhere. Any stuck check (not just Build & Test) gets the same clear red annotation with retry instructions.
• Cleaner UI. PR check list shows one required + N informational instead of 6 mandatory.
• Industry-standard pattern. Tide (Kubernetes) and bors (Rust) both work this way for the same reasons.

Trade-offs (honest)

• Single point of failure. If GitHub drops the dispatch for merge-gate.yml itself, the PR is stuck. Mitigated by dual triggers (pull_request + pull_request_target with concurrency dedup) -- both webhook channels would have to drop simultaneously to brick a PR. Same trade Tide/bors make.
• Adding a check requires editing EXPECTED_CHECKS. This is by design (single source of truth), but it does mean the gate can be out of sync with the ruleset if someone adds a required check via the UI without updating the workflow. Mitigation: the check list is in version control, so PR review catches drift.

Test results (live)

Test	Inputs	Result
shellcheck	shellcheck merge_gate_wait.sh	clean
Aggregate success	All 5 names against PR #862 head SHA db0099e	exit 0, all 5 reported OK (success)
Missing-check timeout	2 names against 0000...0000 SHA, 1m timeout	exit 2, lists both names + recovery instructions
bash 3.2 compatibility	macOS stock bash	passes (parallel indexed arrays, no declare -A)
Self-bootstrap	curl 404 fallback	preserved from #865

Phase 2: flip plan (post-merge, manual via API)

Once you ack the merge, I will run:

# Read current ruleset
gh api repos/microsoft/apm/rulesets/9294522 > /tmp/ruleset.json

# New required_status_checks: ONLY Merge Gate / gate
jq '(.rules[] | select(.type=="required_status_checks") | .parameters.required_status_checks) =
  [{"context":"Merge Gate / gate","integration_id":15368}]' /tmp/ruleset.json > /tmp/ruleset_new.json

jq '{name, target, enforcement, bypass_actors, conditions, rules}' /tmp/ruleset_new.json \
  | gh api -X PUT repos/microsoft/apm/rulesets/9294522 --input -

After flip: only 1 required check (Merge Gate / gate). The 5 underlying checks become informational and continue to run as today.

Rollback

If the gate misbehaves post-flip, restore the prior 5 required-check list via the same API. The underlying workflows continue to run independently of branch protection, so reverting is a one-API-call operation with zero workflow changes needed.

Out of scope

• Changes to underlying CI workflows (ci.yml, ci-integration-pr-stub.yml, ci-integration.yml). They keep doing exactly what they do today.
• Deleting ci-integration-pr-stub.yml. The stubs still need to run for the merge-queue model (real work in ci-integration.yml on merge_group). Only the required-check ruleset entry changes.

[Copilot]

Pull request overview

This PR updates the Merge Gate CI orchestrator to become the single required PR-time verdict by aggregating all currently-required PR checks (Tier 1 + Tier 2 stub checks) via the GitHub Checks API, enabling branch protection to require only Merge Gate / gate.

Changes:

• Expand merge_gate_wait.sh from waiting on a single check to polling a comma-separated list of expected check names and aggregating them into one pass/fail result.
• Update merge-gate.yml to pass the full list of required PR-time check names into the wait script.
• Add a CHANGELOG entry describing the new single-authority Merge Gate model.

Show a summary per file

File	Description
CHANGELOG.md	Adds an Unreleased entry describing Merge Gate aggregating all PR-time required checks into one verdict.
.github/workflows/merge-gate.yml	Passes EXPECTED_CHECKS (all 5 PR-time check names) to the gate wait script; updates header comments to reflect the single-authority model.
.github/scripts/ci/merge_gate_wait.sh	Implements parsing/polling/aggregation for multiple required checks with fail-fast behavior and timeout categorization.

Copilot's findings

• Files reviewed: 3/3 changed files
• Comments generated: 3

[Copilot]

Changelog entries are required to end with the PR number per the repo's Keep a Changelog convention. This new line should end with something like "(#<PR_NUMBER>)" (and keep it as a single line entry under [Unreleased]).

[Copilot]

pending_count is incremented for checks that were pending at the start of the poll iteration, even if they become ok during that same iteration. This means the script can sleep an extra POLL_SEC after the last required check completes. Consider recomputing pending count after updating check_status, or decrementing when a check transitions out of pending.

[Copilot]

The comment says status values include "missing", but check_status is only ever set to pending, ok, or fail. Either update the comment to match reality, or set check_status[i]="missing" when a check has never been observed so the state model stays consistent.

Suggested change

	# Status values: pending, ok, fail, missing
	# Status values: pending, ok, fail

[danielmeppiel]

Phase 2 complete: ruleset flipped

main-protection ruleset (id 9294522) now requires only one status check:

Before (6 required):

• Build & Test (Linux)
• Build (Linux)
• Smoke Test (Linux)
• Integration Tests (Linux)
• Release Validation (Linux)
• Merge Gate / gate

After (1 required):

• Merge Gate / gate

The 5 underlying checks continue to run on every PR; they just become informational signals consumed by the gate. Any future check addition/rename is now a one-line edit to EXPECTED_CHECKS in merge-gate.yml -- no admin permission, no ruleset edit.

Rollback

gh api -X PUT repos/microsoft/apm/rulesets/9294522 --input <file> with the previous 6-check list.