feat(ci): gate merges on maintainer approval via a silent status check

Add a required check that passes only when someone listed in
MAINTAINERS.md has an approving review on the pull request. Unlike
CODEOWNERS and ruleset required reviewers, a status check enforces who
must approve without notifying anyone, and its approver list is a file,
so outside collaborators can be listed.

The job reports through its own exit code rather than a posted commit
status, so it needs no write token and no head SHA. It runs on
pull_request_review, and on merge_group because the queue waits for
required contexts to report on the merge group ref regardless of the
pull request result.

MAINTAINERS.md and the decision helper are read from main, never the
pull request ref, so a contributor cannot add themselves and
self-approve. The helper fails closed when no handles parse.

Signed-off-by: Jim Meyer <jimeyer@nvidia.com>

Author: purp

.github/workflows/core-approval.yml

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: Maintainer Approval
+
+on:
+  merge_group:
+    types: [checks_requested]
+  pull_request_review:
+    types: [submitted, dismissed]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  maintainer-approval:
+    # This name is the required status check context. Changing it silently
+    # breaks the ruleset entry that gates merges on this job.
+    name: OpenShell / Maintainer Approval
+    if: github.repository_owner == 'NVIDIA'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # Check out the default branch, never the pull request head. Both the
+      # maintainer list and the decision helper must come from main: reading
+      # either from the pull request ref would let a contributor add themselves
+      # to the list, or rewrite the decision logic, and self-approve.
+      - name: Check out the maintainer list and helper
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          sparse-checkout: |
+            MAINTAINERS.md
+            tasks/scripts/core_approval.py
+          sparse-checkout-cone-mode: false
+          persist-credentials: false
+
+      - name: Require an approving review from a maintainer
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # merge_group carries no pull request in its payload, but the queue
+          # branch names the entry: gh-readonly-queue/main/pr-3027-<base sha>.
+          MERGE_GROUP_REF: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ -z "${PR_NUMBER:-}" ]; then
+            if [[ "$MERGE_GROUP_REF" =~ /pr-([0-9]+)-[0-9a-f]+$ ]]; then
+              PR_NUMBER="${BASH_REMATCH[1]}"
+            else
+              # Fail closed: an unrecognised ref must never satisfy the gate.
+              echo "::error::No pull request resolved from '$MERGE_GROUP_REF'."
+              exit 1
+            fi
+          fi
+
+          gh api --paginate "repos/$GH_REPO/pulls/$PR_NUMBER/reviews" --jq '.[]' \
+            | jq -s '.' > reviews.json
+
+          # Exits non-zero when no maintainer's latest decisive review is an
+          # approval, and when MAINTAINERS.md yields no handles. That exit code
+          # is the check result; nothing is posted anywhere.
+          python3 tasks/scripts/core_approval.py decide \
+            --maintainers MAINTAINERS.md \
+            --reviews reviews.json

.github/workflows/core-maintainer.yml

@@ -86,7 +86,7 @@ jobs:
           # the body. If they drift, the lookup below silently stops matching
           # and every push stacks another comment.
           COMMENT_ID=$(gh api --paginate "repos/$GH_REPO/issues/$PR_NUMBER/comments" \
-            --jq '.[] | select(.body | startswith("<!-- core-approval-maintainer-delta -->")) | .id' \
+            --jq '.[] | select(.body | startswith("<!-- maintainer-approval-delta -->")) | .id' \
             | head -n 1)
 
           if [ -n "$COMMENT_ID" ]; then

.github/workflows/maintainers-change-alert.yml

@@ -6,7 +6,6 @@ rules:
     ignore:
       # These base-branch workflows never check out or execute pull request
       # head code. Keep each suppression scoped to its reviewed trigger block.
-      - core-approval.yml:6
       - dco.yml:3
       - e2e-label-help.yml:13
       - maintainers-change-alert.yml:6

.github/zizmor.yml

@@ -68,7 +68,7 @@ Do not start substantial issue-backed work until a maintainer has accepted the i
 
 Use agents and the repository skills as needed to understand the affected code, evaluate tradeoffs, implement the smallest coherent change, and verify it. The pull request should explain what changed and how it was tested; it should not substitute an agent transcript for the contributor's understanding.
 
-Every pull request must be approved by someone listed in [MAINTAINERS.md](MAINTAINERS.md) before it can merge. This is enforced by the `OpenShell / Core Approval` status check, which turns green once one of those reviewers approves. Reviews from other contributors are welcome and count toward the general approval requirement, but they do not satisfy this check.
+Every pull request must be approved by someone listed in [MAINTAINERS.md](MAINTAINERS.md) before it can merge. This is enforced by the `OpenShell / Maintainer Approval` status check, which turns green once one of those reviewers approves. Reviews from other contributors are welcome and count toward the general approval requirement, but they do not satisfy this check.
 
 Maintainers are not requested automatically. If your pull request has been idle, ask for a reviewer in the pull request or in the CNCF Slack channel rather than waiting.
 

CONTRIBUTING.md

@@ -10,8 +10,9 @@
 """Decide whether a pull request carries an approval from a listed maintainer.
 
 The logic here is pure so it can be unit tested. The calling workflow does the
-I/O: it fetches MAINTAINERS.md pinned to the default branch, lists the pull
-request's reviews, and passes both in as files.
+I/O: it checks out MAINTAINERS.md from the default branch, lists the pull
+request's reviews, and passes both in as files. `decide` exits non-zero when
+the gate is not satisfied, and that exit code is the check result.
 
 Runs as bare `python3` on the Actions runner, so it must stay stdlib-only.
 """
@@ -34,10 +35,7 @@
 # reviewer's earlier approval intact, which is how GitHub itself treats them.
 DECISIVE_STATES = frozenset({"APPROVED", "CHANGES_REQUESTED", "DISMISSED"})
 
-# GitHub truncates commit status descriptions past this length.
-DESCRIPTION_LIMIT = 140
-
-COMMENT_MARKER = "<!-- core-approval-maintainer-delta -->"
+COMMENT_MARKER = "<!-- maintainer-approval-delta -->"
 
 
 def parse_maintainers(markdown: str) -> set[str]:
@@ -62,34 +60,27 @@ def latest_positions(reviews: list[dict]) -> dict[str, str]:
     return positions
 
 
-def approving_maintainers(
-    reviews: list[dict], maintainers: set[str], author: str
-) -> list[str]:
+def approving_maintainers(reviews: list[dict], maintainers: set[str]) -> list[str]:
     """Return the listed maintainers whose standing position is an approval."""
-    author = author.lower()
     return sorted(
         login
         for login, state in latest_positions(reviews).items()
-        if state == "APPROVED" and login in maintainers and login != author
+        if state == "APPROVED" and login in maintainers
     )
 
 
-def decide(markdown: str, reviews: list[dict], author: str) -> tuple[str, str]:
-    """Return the (state, description) to publish as a commit status."""
+def decide(markdown: str, reviews: list[dict]) -> tuple[bool, str]:
+    """Return whether the gate is satisfied, and a line explaining why."""
     maintainers = parse_maintainers(markdown)
     if not maintainers:
         # Fail closed. An unparseable or empty list must never satisfy the gate.
-        return "failure", "Could not parse any maintainers from MAINTAINERS.md"
+        return False, "Could not parse any maintainers from MAINTAINERS.md"
 
-    approvers = approving_maintainers(reviews, maintainers, author)
+    approvers = approving_maintainers(reviews, maintainers)
     if not approvers:
-        return "failure", "Needs approval from a maintainer listed in MAINTAINERS.md"
+        return False, "Needs approval from a maintainer listed in MAINTAINERS.md"
 
-    shown = ", ".join(f"@{login}" for login in approvers[:3])
-    remainder = len(approvers) - 3
-    if remainder > 0:
-        shown = f"{shown} and {remainder} more"
-    return "success", f"Approved by {shown}"[:DESCRIPTION_LIMIT]
+    return True, "Approved by " + ", ".join(f"@{login}" for login in approvers)
 
 
 def format_delta(before: str, after: str) -> str:
@@ -114,7 +105,7 @@ def format_delta(before: str, after: str) -> str:
             lines.append("")
         lines.append(
             "Confirm every change is intended. Anyone listed here can single-handedly "
-            "satisfy `OpenShell / Core Approval`."
+            "satisfy `OpenShell / Maintainer Approval`."
         )
 
     if not new:
@@ -132,7 +123,7 @@ def build_parser() -> argparse.ArgumentParser:
     subcommands = parser.add_subparsers(dest="command", required=True)
 
     decide_cmd = subcommands.add_parser(
-        "decide", help="print the commit status to publish, as 'state<TAB>description'"
+        "decide", help="exit 0 when a listed maintainer has approved, 1 otherwise"
     )
     decide_cmd.add_argument(
         "--maintainers",
@@ -146,9 +137,6 @@ def build_parser() -> argparse.ArgumentParser:
         type=Path,
         help="JSON array returned by the list-reviews API",
     )
-    decide_cmd.add_argument(
-        "--author", default="", help="pull request author, excluded from approvers"
-    )
 
     diff_cmd = subcommands.add_parser(
         "diff", help="print a review comment describing the approver set change"
@@ -167,17 +155,16 @@ def main(argv: list[str] | None = None) -> int:
 
     if args.command == "decide":
         reviews = json.loads(args.reviews.read_text(encoding="utf-8"))
-        state, description = decide(
-            args.maintainers.read_text(encoding="utf-8"), reviews, args.author
-        )
-        print(f"{state}\t{description}")
-    else:
-        print(
-            format_delta(
-                args.before.read_text(encoding="utf-8"),
-                args.after.read_text(encoding="utf-8"),
-            )
+        approved, reason = decide(args.maintainers.read_text(encoding="utf-8"), reviews)
+        print(reason)
+        return 0 if approved else 1
+
+    print(
+        format_delta(
+            args.before.read_text(encoding="utf-8"),
+            args.after.read_text(encoding="utf-8"),
         )
+    )
     return 0