fix(ci): add merge_group trigger to Merge Gate so it reports in queue

[danielmeppiel]

Problem

Branch protection / merge-queue ruleset requires the gate check, but merge-gate.yml only triggered on pull_request and workflow_dispatch. In the merge queue, GitHub fires merge_group events against a temp merge commit -- the gate check was never created on that SHA, so PRs sat in the queue with gate stuck in "Expected -- Waiting for status to be reported" indefinitely.

Concrete example: PR #899. All real checks green, only gate perpetually pending, blocking the merge.

Fix

Single-authority gate pattern preserved -- one ruleset entry, one mental model -- now extended to merge queue.

.github/workflows/merge-gate.yml

• Add merge_group trigger (types: [checks_requested]) alongside existing pull_request + workflow_dispatch.
• Resolve head SHA per event:
  • workflow_dispatch -> gh api .../pulls/N --jq .head.sha
  • merge_group -> github.event.merge_group.head_sha (the temp merge commit, NOT the PR head)
  • pull_request -> github.event.pull_request.head.sha
• Branch EXPECTED_CHECKS by event:
  • PR / dispatch: Build & Test (Linux),APM Self-Check
  • Merge queue: above + Build (Linux),Smoke Test (Linux),Integration Tests (Linux),Release Validation (Linux) (the ci-integration.yml checks)
• Bump TIMEOUT_MIN 30 -> 55 and job timeout-minutes 35 -> 60. ci-integration.yml's theoretical worst-case critical path is ~50m (Build -> Smoke -> Integration[20m] -> Release Validation[20m]); current observation is ~5m. Sized for growth.
• Update header comment + recovery instructions for both contexts.

.github/scripts/ci/merge_gate_wait.sh

• New optional EVENT_NAME env var. On exit code 2 ("check never started"), emit event-aware recovery: in merge_group context, pushing a commit does NOT retrigger the merge_group event -- the user must remove and re-add the PR to the queue.
• Add &filter=latest to the Checks API query so GitHub returns only the latest run per name, removing reliance on client-side sort and pagination.

Why not just list checks directly in the merge-queue ruleset?

Considered. Rejected because the gate pattern works well at the PR tier today, and stretching it to the merge-queue tier keeps a single ruleset entry (gate), a single mental model, and a single place to add/rename checks. Listing checks directly would require ruleset edits on every check rename.

Concurrency

Existing key merge-gate-${{ pull_request.number || inputs.pr_number || github.ref }} falls through to github.ref in merge_group context. That ref is refs/heads/gh-readonly-queue/main/pr-N-<sha> -- unique per queue entry -- so cancel-in-progress dedupes correctly within a single temp branch and never collides across PR <-> merge_group channels.

Self-deadlock

gate is intentionally absent from EXPECTED_CHECKS in both event contexts.

Audit

Design audited against live GitHub docs by a sub-agent grounded in:

• merge_group webhook payload -- confirms checks_requested is the only action and head_sha field is correct.
• Managing a merge queue -- confirms checks must be reported against the merge_group head SHA, and that branch-protection required checks apply to both PR and queue contexts.
• Checks API runs -- confirms filter=latest semantics and per_page behavior.

Audit findings folded into this PR:

• BLOCKER (fixed): Recovery message in merge_gate_wait.sh was wrong for merge_group (told users to push a commit). Now event-aware.
• NICE-TO-HAVE (fixed): Replaced client-side sort_by(started_at) with server-side filter=latest.
• IMPORTANT (fixed): Bumped poll budget + job timeout above the theoretical worst-case critical path of ci-integration.yml.

Audit verdict: SHIP with these specific changes (all included).

Pre-existing observation flagged but out of scope: paths-ignore on the pull_request trigger means doc-only PRs would never run gate and theoretically could not satisfy the PR ruleset. Not actually a problem today (doc-only PRs aren't blocked in practice -- worth a separate investigation).

Validation

• bash -n .github/scripts/ci/merge_gate_wait.sh clean.
• YAML parses; triggers [pull_request, merge_group, workflow_dispatch]; env wiring matches spec.
• This PR's own gate run will exercise the pull_request path; merging into the queue will exercise the merge_group path.

Fixes the queue-stall behaviour observed on #899.

[Copilot]

Pull request overview

Extends the repository's single-authority CI "gate" workflow so it also reports a gate check in merge queue (merge_group) context, preventing merge queue entries from stalling with "Expected -- Waiting for status to be reported".

Changes:

• Add merge_group trigger to .github/workflows/merge-gate.yml and resolve the correct SHA per event type.
• Branch EXPECTED_CHECKS to include Tier 2 (ci-integration.yml) checks when running under merge_group, and increase timeouts accordingly.
• Update .github/scripts/ci/merge_gate_wait.sh to accept an optional EVENT_NAME, improve recovery messaging for merge queue, and query the Checks API with filter=latest.

Show a summary per file

File	Description
.github/workflows/merge-gate.yml	Triggers gate on merge_group and polls the correct set of checks for merge queue SHAs.
.github/scripts/ci/merge_gate_wait.sh	Adds merge-queue-aware recovery messaging and improves check-run querying with filter=latest.

Copilot's findings

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

[Copilot]

pull_request.paths-ignore excludes docs/** (and a couple of root files). If the ruleset requires the gate check for PRs, a docs-only PR can end up with gate never being created ("Expected -- Waiting") because both Merge Gate and ci.yml are skipped. Consider either removing these paths-ignore entries (in both workflows) or adding explicit logic so docs-only PRs still report a gate result without waiting on checks that will never run.

See below for a potential fix:

[Copilot]

The new comment says filter=latest "avoids client-side sort", but the code still does sort_by(.started_at) | reverse when selecting .[0]. Consider tweaking the comment to reflect reality (e.g., filter=latest reduces pagination/rerun ambiguity; client-side sort remains as a defensive tie-breaker).

Suggested change

	# latest run per name (avoids client-side sort / pagination races
	# when a check has been re-run on the same SHA).
	# latest run per name. This reduces pagination and re-run ambiguity
	# on the same SHA; the client-side sort below remains as a defensive
	# tie-breaker before selecting .[0].