Phase 1: distributed CODEOWNERS and automated reviewer routing (#4184) (#4189)

* Phase 1: distributed CODEOWNERS and automated reviewer routing (#4184) - Replace the individual default CODEOWNERS owner with the core-maintainer team and add domain team ownership for extensions, plugins, content, hooks, workflows, .github, and eng. - Add .github/review-routing.yml as the single source of truth for reviewer pools, routes, labels, and SLA settings (ships in dry-run mode). - Add eng/review-routing.mjs (+ unit tests) with business-day math, least-loaded reviewer selection, routing and escalation planning, and workflow_run artifact validation. - Add Review Routing (workflow_run/dispatch/schedule), Review Routing Request (read-only needs-reviewer reader), and Review Escalation (weekday schedule) workflows. - Add needs-reviewer, review-overdue, review-escalated to setup-labels. - Document the model in docs/maintainers/review-routing.md. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address review feedback on reviewer routing and escalation - Escalate at routedOn + escalation business days (Mon -> Fri) - Leave labels untouched when requestReviewers fails and fail the job - Serialize read/plan/apply per PR across routing and escalation - Treat Label PR Intent artifact labels as authoritative - Re-route to an uncovered pool on head changes without restarting SLA - Use the due-label timestamp as the review boundary - Fall back to pool/escalation teams and report what was requested Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address second-round review feedback on review routing (#4184) - CODEOWNERS: route /hooks/ and /workflows/ to content reviewers, drop the separate /.github/workflows/ rule, and leave per-resource owner lines as on main (their removal is deferred to a separate cleanup). - Routing: ignore pending requests for unavailable reviewers when checking coverage; needs-reviewer excludes prior reviewers and changes nothing when no new reviewer can be requested. - Escalation comments show the actual routing date. - Cap sweep matrices at 256 targets and defer the remainder. - Docs: best-effort load balancing, matrix cap, and needs-reviewer semantics. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Route workflow and hooks labels to the content pool (#4184) Drop the workflow-security reviewer pool per maintainer feedback: agentic workflows and hooks are reviewed like other content, and the repository's own GitHub Actions workflows stay with core maintainers. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Pin routing contract in tests; make CONTRIBUTING routing note dry-run aware - Assert the exact label-to-pool mapping and priority order, pool set, and default/escalation pools for the shipped config. - CONTRIBUTING.md: describe automatic routing as active only once dry_run is turned off. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Simplify dry_run validation condition Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Aaron Powell <me@aaron-powell.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-10-12 23:04:14 +00:00 · 2026-10-01 00:51:10 +00:00
parent c442f0d917
commit 0c54bcee82
11 changed files with 2194 additions and 1 deletions
@@ -0,0 +1,160 @@
+name: Review Escalation
+
+# Enforces the review SLA from .github/review-routing.yml for routed PRs
+# (those with a `review-due:YYYY-MM-DD` label):
+# - no review after the due date -> request a backup (or a team), add `review-overdue`
+# - no review escalation_business_days after routing -> request the
+#   core-maintainer pool, add `review-escalated`
+# - first human review since routing -> clear the SLA labels
+# Business days skip weekends and configured holidays, so the schedule only
+# runs Monday–Friday.
+#
+# The read-only `plan` job selects PRs needing action; the `escalate` job then
+# handles each PR in the `review-routing-pr-<number>` concurrency group shared
+# with Review Routing. Only trusted default-branch code is executed.
+
+on:
+  schedule:
+    - cron: "0 14 * * 1-5"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+    outputs:
+      targets: ${{ steps.plan.outputs.targets }}
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Select pull requests needing SLA action
+        id: plan
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const routing = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'review-routing.mjs')).href);
+            const config = routing.loadReviewRoutingConfig(path.join(process.env.GITHUB_WORKSPACE, '.github', 'review-routing.yml'));
+
+            const plans = await routing.planEscalationSweep({ github, owner: context.repo.owner, repo: context.repo.repo, config });
+            const actionable = plans.filter((plan) => ['reviewed', 'overdue', 'escalate'].includes(plan.action));
+
+            await core.summary.addRaw(routing.formatResultsSummary(actionable, { title: 'Review escalation plan', dryRun: config.dryRun })).write();
+            const limited = routing.limitTargets(actionable.map((plan) => ({ pr: plan.prNumber })));
+            if (limited.deferred > 0) core.warning(`${limited.deferred} PR(s) exceed the ${routing.MAX_MATRIX_TARGETS}-job matrix limit and are deferred to the next run.`);
+            core.setOutput('targets', JSON.stringify(limited.targets));
+
+  escalate:
+    needs: plan
+    if: needs.plan.outputs.targets != '' && needs.plan.outputs.targets != '[]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    strategy:
+      fail-fast: false
+      # Sequential so each PR sees reviewer load updated by the previous one.
+      max-parallel: 1
+      matrix:
+        target: ${{ fromJSON(needs.plan.outputs.targets) }}
+    concurrency:
+      group: review-routing-pr-${{ matrix.target.pr }}
+      cancel-in-progress: false
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Apply review SLA
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          TARGET_PR: ${{ matrix.target.pr }}
+        with:
+          script: |
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const routing = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'review-routing.mjs')).href);
+            const config = routing.loadReviewRoutingConfig(path.join(process.env.GITHUB_WORKSPACE, '.github', 'review-routing.yml'));
+
+            const prNumber = Number(process.env.TARGET_PR);
+            if (!Number.isInteger(prNumber) || prNumber < 1) throw new Error(`Invalid target PR: ${process.env.TARGET_PR}`);
+
+            const plan = await routing.escalatePullRequest({
+              github,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              config,
+              prNumber,
+              log: core,
+            });
+
+            await core.summary.addRaw(routing.formatResultsSummary([plan], { title: `Review escalation for #${prNumber}`, dryRun: config.dryRun })).write();
+            if (plan.requestError) core.setFailed(`Reviewer request failed for PR #${prNumber}: ${plan.requestError}`);
+
+  cleanup:
+    needs: plan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Delete stale review-due labels
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const routing = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'review-routing.mjs')).href);
+            const config = routing.loadReviewRoutingConfig(path.join(process.env.GITHUB_WORKSPACE, '.github', 'review-routing.yml'));
+            const deleted = await routing.cleanupStaleDueLabels({ github, owner: context.repo.owner, repo: context.repo.repo, config, log: core });
+            core.info(`Stale review-due labels ${config.dryRun ? 'that would be ' : ''}deleted: ${deleted.join(', ') || 'none'}`);
@@ -0,0 +1,45 @@
+name: Review Routing Request
+
+# Reader half of the needs-reviewer routing flow. Runs with a read-only token
+# and only records which PR asked for a reviewer; the privileged Review Routing
+# workflow validates this artifact and performs the request.
+#
+# Labels added with GITHUB_TOKEN do not emit `labeled` events, so automation
+# should dispatch review-routing.yml directly (or rely on its scheduled sweep).
+
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  capture:
+    runs-on: ubuntu-latest
+    if: github.event.label.name == 'needs-reviewer'
+    steps:
+      - name: Record routing request
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const outDir = path.join(process.env.RUNNER_TEMP, 'review-routing-request');
+            fs.mkdirSync(outDir, { recursive: true });
+            fs.writeFileSync(path.join(outDir, 'result.json'), `${JSON.stringify({
+              schema_version: 'review-routing-request/v1',
+              event: 'pull_request',
+              pr_number: context.payload.pull_request.number,
+              head_sha: context.payload.pull_request.head.sha,
+              run_id: process.env.GITHUB_RUN_ID,
+            }, null, 2)}\n`);
+
+      - name: Upload routing request artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: review-routing-request
+          path: ${{ runner.temp }}/review-routing-request/result.json
+          if-no-files-found: error
+          retention-days: 3
@@ -0,0 +1,197 @@
+name: Review Routing
+
+# Requests a reviewer from the pool configured in .github/review-routing.yml
+# and marks the PR with a `review-due:YYYY-MM-DD` label.
+#
+# Triggers:
+# - workflow_run of "Label PR Intent": route new PRs, and re-route when a new
+#   head changes the target pool (trusted artifact, authoritative intent labels).
+# - workflow_run of "Review Routing Request": a human added `needs-reviewer`.
+# - workflow_dispatch with pr_number: automation (e.g. `/request-review`) asks
+#   for routing after adding `needs-reviewer` with GITHUB_TOKEN.
+# - schedule / workflow_dispatch without pr_number: sweep all open PRs.
+#
+# The read-only `plan` job selects target PRs. The `route` job then handles each
+# PR in the `review-routing-pr-<number>` concurrency group (shared with Review
+# Escalation) so read/plan/apply never overlaps for the same PR.
+#
+# Only trusted code from the default branch is checked out. PR code is never
+# checked out or executed.
+
+on:
+  workflow_run:
+    workflows: ["Label PR Intent", "Review Routing Request"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "Pull request number to route (leave empty to sweep all open PRs)"
+        required: false
+        type: string
+  schedule:
+    - cron: "17 * * * *"
+
+permissions: {}
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    if: >-
+      github.event_name != 'workflow_run' ||
+      (github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success')
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    outputs:
+      targets: ${{ steps.plan.outputs.targets }}
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Download reader artifact
+        id: download
+        if: github.event_name == 'workflow_run'
+        continue-on-error: true
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ github.event.workflow_run.name == 'Label PR Intent' && 'label-pr-intent-result' || 'review-routing-request' }}
+          path: ${{ runner.temp }}/review-routing-input
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Select pull requests to route
+        id: plan
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          PR_NUMBER_INPUT: ${{ inputs.pr_number }}
+          DOWNLOAD_OUTCOME: ${{ steps.download.outcome }}
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const routing = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'review-routing.mjs')).href);
+            const config = routing.loadReviewRoutingConfig(path.join(process.env.GITHUB_WORKSPACE, '.github', 'review-routing.yml'));
+            const { owner, repo } = context.repo;
+            const targets = [];
+
+            if (context.eventName === 'workflow_run') {
+              if (process.env.DOWNLOAD_OUTCOME !== 'success') {
+                core.info('No reader artifact was available; nothing to route.');
+              } else {
+                const artifact = JSON.parse(fs.readFileSync(path.join(process.env.RUNNER_TEMP, 'review-routing-input', 'result.json'), 'utf8'));
+                const resolved = await routing.resolveWorkflowRunArtifact({ github, owner, repo, workflowRun: context.payload.workflow_run, artifact });
+                if (resolved.skip) {
+                  core.info(`Skipping: ${resolved.skip}`);
+                } else {
+                  targets.push({
+                    pr: resolved.prNumber,
+                    head_sha: resolved.headSha,
+                    intent_labels: resolved.intentLabels === null ? '' : JSON.stringify(resolved.intentLabels),
+                  });
+                }
+              }
+            } else if (process.env.PR_NUMBER_INPUT) {
+              const prNumber = Number(process.env.PR_NUMBER_INPUT);
+              if (!Number.isInteger(prNumber) || prNumber < 1) {
+                core.setFailed(`Invalid pr_number input: ${process.env.PR_NUMBER_INPUT}`);
+                return;
+              }
+              targets.push({ pr: prNumber, head_sha: '', intent_labels: '' });
+            } else {
+              const plans = await routing.planRoutingSweep({ github, owner, repo, config });
+              for (const plan of plans.filter((candidate) => candidate.action === 'route')) {
+                targets.push({ pr: plan.prNumber, head_sha: '', intent_labels: '' });
+              }
+              await core.summary
+                .addRaw(routing.formatResultsSummary(plans.filter((plan) => plan.action === 'route'), { title: 'Review routing sweep plan', dryRun: config.dryRun }))
+                .write();
+            }
+
+            const limited = routing.limitTargets(targets);
+            if (limited.deferred > 0) core.warning(`${limited.deferred} PR(s) exceed the ${routing.MAX_MATRIX_TARGETS}-job matrix limit and are deferred to the next sweep.`);
+            core.info(`Routing targets: ${limited.targets.map((target) => `#${target.pr}`).join(', ') || 'none'}`);
+            core.setOutput('targets', JSON.stringify(limited.targets));
+
+  route:
+    needs: plan
+    if: needs.plan.outputs.targets != '' && needs.plan.outputs.targets != '[]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    strategy:
+      fail-fast: false
+      # Sequential so each PR sees reviewer load updated by the previous one.
+      max-parallel: 1
+      matrix:
+        target: ${{ fromJSON(needs.plan.outputs.targets) }}
+    concurrency:
+      group: review-routing-pr-${{ matrix.target.pr }}
+      cancel-in-progress: false
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Route reviewer
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          TARGET_PR: ${{ matrix.target.pr }}
+          TARGET_HEAD_SHA: ${{ matrix.target.head_sha }}
+          TARGET_INTENT_LABELS: ${{ matrix.target.intent_labels }}
+        with:
+          script: |
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const routing = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'review-routing.mjs')).href);
+            const config = routing.loadReviewRoutingConfig(path.join(process.env.GITHUB_WORKSPACE, '.github', 'review-routing.yml'));
+
+            const prNumber = Number(process.env.TARGET_PR);
+            if (!Number.isInteger(prNumber) || prNumber < 1) throw new Error(`Invalid target PR: ${process.env.TARGET_PR}`);
+            const headSha = process.env.TARGET_HEAD_SHA || null;
+            if (headSha && !/^[0-9a-f]{40}$/i.test(headSha)) throw new Error('Invalid target head SHA');
+            const intentLabels = process.env.TARGET_INTENT_LABELS
+              ? routing.validateIntentLabels(JSON.parse(process.env.TARGET_INTENT_LABELS))
+              : null;
+
+            const plan = await routing.routePullRequest({
+              github,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              config,
+              prNumber,
+              intentLabels,
+              expectedHeadSha: headSha,
+              log: core,
+            });
+
+            await core.summary.addRaw(routing.formatResultsSummary([plan], { title: `Review routing for #${prNumber}`, dryRun: config.dryRun })).write();
+            if (plan.requestError) core.setFailed(`Reviewer request failed for PR #${prNumber}: ${plan.requestError}`);
@@ -89,6 +89,19 @@ jobs:
              'awaiting-approval': {
                color: 'FBCA04',
                description: 'External plugin awaiting maintainer approval'
+              },
+              // Review routing labels (see .github/review-routing.yml)
+              'needs-reviewer': {
+                color: 'D4C5F9',
+                description: 'Request automated reviewer routing for this PR'
+              },
+              'review-overdue': {
+                color: 'E99695',
+                description: 'First review is past its due date; a backup reviewer was requested'
+              },
+              'review-escalated': {
+                color: 'B60205',
+                description: 'Review escalated to the core-maintainer pool'
              }
            };