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>
This commit is contained in:
James Montemagno
2026-10-01 00:51:10 +00:00
committed by GitHub
co-authored by Copilot App Copilot Autofix powered by AI Aaron Powell
parent c442f0d917
commit 0c54bcee82
11 changed files with 2194 additions and 1 deletions
+85
View File
@@ -0,0 +1,85 @@
# Review routing configuration — single source of truth for reviewer pools.
#
# Read by eng/review-routing.mjs from the Review Routing and Review Escalation
# workflows. See docs/maintainers/review-routing.md for the full operating model.
#
# Handles are GitHub logins without the leading "@". Team values use the
# "<org>/<team-slug>" form. Keep every pool at three or more reviewers with
# cross-time-zone coverage before turning off dry_run.
version: 1
# When true, workflows only log the actions they would take (no reviewer
# requests, labels, or comments). Set to false once the teams and pools below
# are populated.
dry_run: true # TODO: set to false after the reviewer pools are staffed.
sla:
# Business days (Monday–Friday, UTC, excluding holidays) after routing by
# which a first review is expected. The date is shown in the review-due label.
first_review_business_days: 2
# Business days after routing before the PR escalates to the core pool.
escalation_business_days: 4
# Optional non-working days (YYYY-MM-DD, UTC) skipped by business-day math.
holidays: []
labels:
needs_reviewer: needs-reviewer
due_prefix: "review-due:"
overdue: review-overdue
escalated: review-escalated
# Pool that receives escalations and acts as the last-resort fallback.
escalation_pool: core-maintainers
# Pool used when no intent label matches a route below.
default_pool: core-maintainers
pools:
core-maintainers:
team: github/awesome-copilot-core-maintainers
reviewers: [] # TODO: add at least three core maintainers.
backup: [] # TODO: optional; escalation already targets this pool.
canvas:
team: github/awesome-copilot-canvas-reviewers
reviewers: [] # TODO: add at least three canvas reviewers.
backup: [] # TODO: add backup reviewers for canvas extensions.
plugin:
team: github/awesome-copilot-plugin-reviewers
reviewers: [] # TODO: add at least three plugin reviewers.
backup: [] # TODO: add backup reviewers for plugins.
content:
team: github/awesome-copilot-content-reviewers
reviewers: [] # TODO: add at least three reviewers for skills, agents, and instructions.
backup: [] # TODO: add backup content reviewers.
# Intent labels (applied by .github/workflows/label-pr-intent*.yml) mapped to
# pools. Order is priority: the first route whose label is on the PR wins.
routes:
- label: canvas-extension
pool: canvas
- label: external-plugin
pool: plugin
- label: plugin
pool: plugin
- label: skills
pool: content
- label: agent
pool: content
- label: instructions
pool: content
- label: workflow
pool: content
- label: hooks
pool: content
- label: website-update
pool: core-maintainers
# Reviewers temporarily unavailable (vacation, leave). They are never selected.
unavailable: []
# PR authors that are never routed (for example, automation accounts).
skip_authors: []
# PRs carrying any of these labels are not routed or escalated.
skip_labels: []
+160
View File
@@ -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
+197
View File
@@ -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}`);
+13
View File
@@ -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'
}
};