Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-review-require-labels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `review.require_labels` — a PR-side approval allow-list for reviews, the counterpart of `project.issue_filter.require_labels`: when set, the hive reviews only PRs carrying at least one of the labels. Enforced server-side in the cadence reviewer's PR list, the fan-out dispatch planner and the `hive-review` relay (which re-reads the PR's labels and refuses any review, thread reply or verdict on an unlabelled PR, audited as `review_label_gate_refused`), so a prompt cannot bypass it. New **Settings → Features → Review Gate → "Only review labelled PRs"** toggle with a label list, saved through `PUT /api/config/review`. Empty (the default) changes nothing. Reported-by: @joerunde (a1-vllm-spyre spoke: "the team wants reviews gated — run only when a label is added to a PR").
15 changes: 15 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package main

import (
Expand Down Expand Up @@ -10453,6 +10453,9 @@
func() bool { return cfg.Review.CombinedPerspectives },
func() int { return cfg.Review.MaxReviewsPerHead },
)
// review.require_labels (PR approval allow-list): the relay's half of the
// gate, read live so a Features-tab edit applies to the next request.
client.SetReviewRequireLabels(func() []string { return cfg.Review.RequireLabels })
}

// reviewBacklogRouting resolves review.severity / review.backlog and the
Expand Down Expand Up @@ -10801,6 +10804,7 @@
prAgents := auditPRAgents(cfg.Project.Org, time.Now().Add(-auditPRAttributionWindow), "")
candidates := make([]github.PullRequest, 0, len(actionable.PRs.Items)+len(actionable.PRs.Held))
seenPRs := map[string]bool{}
labelGated := 0
addCandidates := func(items []github.PullRequest) {
for _, pr := range items {
fullRepo := fullRepoName(pr.Repo, cfg.Project.Org)
Expand All @@ -10809,11 +10813,22 @@
continue
}
seenPRs[key] = true
// review.require_labels: an unlabelled PR is never dispatched
// to the swarm. The relay refuses it independently.
if !cfg.Review.AdmitsPRLabels(pr.Labels) {
labelGated++
continue
}
candidates = append(candidates, pr)
}
}
addCandidates(actionable.PRs.Items)
addCandidates(actionable.PRs.Held)
if labelGated > 0 && logger != nil {
logger.Info("review label gate withheld PRs from review dispatch",
"withheld", labelGated, "candidates", len(candidates),
"require_labels", strings.Join(cfg.Review.NormalizedRequireLabels(), ","))
}
sort.SliceStable(candidates, func(i, j int) bool {
ri, rj := candidates[i].ReviewRank, candidates[j].ReviewRank
if ri > 0 && rj > 0 && ri != rj {
Expand Down
1 change: 1 addition & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1031,6 +1031,7 @@ Semantics:
- An issue must carry **at least one** required label to be eligible. Matching is case-insensitive and **exact** (a prefix like `approved-for-agents-maybe` does not satisfy `approved-for-agents` — prefix matching would over-admit through an approval gate).
- **Exempt wins on conflict**: an issue carrying both an exempt label and a required label stays excluded. There is deliberately no separate `exclude_labels` field — the exempt list *is* the exclusion mechanism, applied first.
- PRs and the Hold list are unaffected: open PRs are in-flight work, and held issues still appear under On Hold.
- PRs have their own, separate allow-list for **reviews**: `review.require_labels` (Settings → Features → Review Gate → "Only review labelled PRs") keeps the hive from reviewing a PR until it carries an approval label; see [review-swarm.md](review-swarm.md#only-review-labelled-prs-reviewrequire_labels). Use a distinct label from the issue gate if the two approvals mean different things to your maintainers.

Both polarities are enforced at **enumeration** — the point where GitHub issues become the hive's actionable set — not in the prompt. A filtered issue never enters the queue, never appears in a kick, never triggers plan-from-label, and cannot be re-selected by a confused (or prompt-injected) agent re-listing the repo. Kick prompts additionally state the active require policy so agents know the list is intentionally short. Both lists are edited on the Labels tab; an active require gate is also noted read-only under **Projects**, and hub-managed hives can receive `issue_filter` with their project config over the heartbeat.

Expand Down
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,8 @@ Review Pipeline shows pull requests by stage first; Review Queue lists the same

Each open PR in the stage the review pipeline derived for it (GET /api/review/pipeline), with reviewers, P0–P3 findings, the fix-loop counter and the next action.

When **Settings → Features → Review Gate → Only review labelled PRs** (`review.require_labels`) is on, PRs without one of the approval labels stay in the *unreviewed* stage until a maintainer labels them: the planner never dispatches them and the relay refuses reviews on them.

**What it tells you.** Each column is one stage of the review loop: unreviewed, reviewing, changes requested, fixing, waiting for a human, approved, merged and abandoned. Each card shows the pull request, who has reviewed it, how many findings were raised at each severity and what should happen next.

**How the numbers are worked out.** Hive reads the last review results it recorded for each pull request and places the card in a stage from those results alone. The collapsible Pipeline tile header shows how many pull requests are on the board. Nothing is fetched from GitHub when you open it.
Expand Down
8 changes: 8 additions & 0 deletions src/docs/dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,14 @@ through `/api/config/auto-merge`, with a watched-repo multi-select (no
selection means all watched repositories), role selector, GitHub permission
switch, and excluded-label list.

Governor settings **Features → Review Gate** includes the owner-only
**Only review labelled PRs** toggle with a comma-separated label list. It
edits `review.require_labels` through `/api/config/review`; on, the hive
reviews only PRs carrying one of the labels (enforced in the reviewer kick
list, the review dispatch planner and the hive-review relay — see
[review-swarm.md](review-swarm.md#only-review-labelled-prs-reviewrequire_labels)).
Off (the default) sends an empty list and every open PR stays reviewable.

The cadence table starts each agent row with the same `1`/`0` Agent power
rocker used in the agent settings panel, so owners can enable or disable an
agent from the table; disabled rows are dimmed, and read-only viewers see the
Expand Down
41 changes: 41 additions & 0 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,7 @@ review:
contributor_prs:
base_sync: false # optional; let GitHub update-branch unstick hive-authored fork PRs (default off)
priority_labels: false # optional; mirror the PR review queue rank onto review-priority/* labels (default off)
require_labels: [] # optional; review ONLY PRs carrying one of these labels (default empty = every open PR); see "Only review labelled PRs"
pending_ttl: 45m # optional; re-dispatch a review that has posted no verdict after this long (default 45m)
pending_fix_ttl: 2h # optional; dispatch the next bounded fix attempt when a fixer has pushed no new head after this long (default 2h; negative disables expiry)
max_redispatch: 3 # optional; expiries per head before the PR is held for a human (default 3)
Expand All @@ -202,6 +203,46 @@ review:

### Blocking line (`review.severity`, `review.backlog`)

### Only review labelled PRs (`review.require_labels`)

`review.require_labels` is the PR-side counterpart of the issue approval gate
`project.issue_filter.require_labels` ([agent-configuration.md](agent-configuration.md#label-policy-which-issues-agents-may-work)):
a team that wants hive reviews **only on PRs a maintainer has opted in** names
the label(s) here, and the hive reviews nothing else.

```yaml
review:
require_labels: [hive-review] # a PR is reviewed only if it carries at least one of these
```

Dashboard: **Settings → Features → Review Gate → "Only review labelled PRs"**
(toggle + comma-separated label list; saved through `PUT /api/config/review`
into the dashboard overlay, so it survives restarts and ACMM pack re-applies —
it is a `review.*` key, not an agent block).

Semantics:

- **Absent/empty = no gate.** Every open PR stays reviewable; no existing hive
goes quiet on upgrade.
- A PR must carry **at least one** listed label. Matching is case-insensitive
and **exact** (`approved-for-review` does not satisfy `approved`).
- **Enforced server-side in three places**, so a prompt cannot route around it:
the cadence reviewer's `${PR_LIST}` and the fan-out dispatch planner never
offer an unlabelled PR (log line `review label gate withheld PRs from …`),
and the `hive-review` relay refuses any request — review, thread reply,
resolution or bare `record_verdict` — on a PR that lacks the label after
re-reading its labels with the App token (`.denied`, audit
`review_label_gate_refused`). A failed label fetch is retried, never waved
through.
- The reviewer's kick carries a `REVIEW LABEL GATE` notice naming the labels,
mirroring the issue-filter notice.
- Labels are **never created** by the hive; name one the repo already
maintains. Exempt/hold labels still exclude a PR that also carries an
approval label.
- It is independent of `review.require_approval`: a hive that gates merge on
review AND gates review on a label simply does not merge unlabelled PRs
until a person labels (or merges) them.

`review.severity.block_at` is the lowest finding priority that still blocks merge, on the P0–P3 scale (critical → P0, high → P1, medium → P2, low/info → P3). **Settings → Features → Review Gate → Severity & backlog** offers three presets: *Strict (P0–P2 block)* sets `P2`, *Ship fast (P0–P1 block)* sets `P1`, and *Everything blocks* sets `P3`. Unset keeps today's behaviour. Findings below the line are posted as non-blocking comments when `comment_below` is true (default) and filed as follow-up work when `backlog_below` is true (default).

`review.backlog` says where that follow-up work goes:
Expand Down
12 changes: 12 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -7565,6 +7565,18 @@ type ReviewConfig struct {
// a repo that does not already have them is skipped. Off by default: a
// label on every PR is churn a repo must ask for.
PriorityLabels bool `yaml:"priority_labels,omitempty" json:"priority_labels,omitempty"`
// RequireLabels is the PR-side approval allow-list, the review
// counterpart of project.issue_filter.require_labels. Non-empty: a PR is
// reviewed by the hive only if it carries AT LEAST ONE of these labels
// (case-insensitive exact match). It is enforced in two places so a
// prompt cannot route around it: the reviewer kick lists and the review
// dispatch planner never offer an unlabelled PR, and the hive-review
// relay refuses to post on one. Absent/empty keeps today's behaviour —
// every open PR is reviewable — so no existing hive goes quiet on
// upgrade. The label is never created: name one the governed repos
// already maintain. Operator-added hold/exempt labels still exclude a PR
// that also carries an approval label.
RequireLabels []string `yaml:"require_labels,omitempty" json:"require_labels,omitempty"`
// VerdictLabels mirrors the review swarm's state for each PR's current
// head onto exactly one label (hivecommons/hive#13833): reviewing while
// the head's review is pending, then the settled verdict. Independent of
Expand Down
52 changes: 52 additions & 0 deletions src/pkg/config/review_require_labels.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
package config

import "strings"

// ReviewRequireLabelsSkipReason is the one phrase every surface uses when
// review.require_labels keeps a PR out of review, so a kick list, the relay's
// refusal and the governor log all read the same.
const ReviewRequireLabelsSkipReason = "review.require_labels: PR carries none of the approval labels"

// NormalizedRequireLabels returns review.require_labels trimmed and without
// blanks or duplicates, in the operator's order. An all-blank list is nil,
// which every caller reads as "gate off".
func (r ReviewConfig) NormalizedRequireLabels() []string {
if len(r.RequireLabels) == 0 {
return nil
}
out := make([]string, 0, len(r.RequireLabels))
seen := map[string]bool{}
for _, l := range r.RequireLabels {
l = strings.TrimSpace(l)
if l == "" {
continue
}
key := strings.ToLower(l)
if seen[key] {
continue
}
seen[key] = true
out = append(out, l)
}
if len(out) == 0 {
return nil
}
return out
}

// RequireLabelsEnabled reports whether the PR review label gate is on.
func (r ReviewConfig) RequireLabelsEnabled() bool {
return len(r.NormalizedRequireLabels()) > 0
}

// AdmitsPRLabels is the review-side counterpart of IssueFilterConfig.Admits:
// with review.require_labels empty every PR is admitted; otherwise the PR must
// carry at least one of the configured labels (case-insensitive exact match,
// never prefix — "approved-for-review" must not admit under "approved").
func (r ReviewConfig) AdmitsPRLabels(labels []string) bool {
required := r.NormalizedRequireLabels()
if len(required) == 0 {
return true
}
return anyLabelMatches(required, labels)
}
46 changes: 46 additions & 0 deletions src/pkg/config/review_require_labels_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
package config

import "testing"

func TestReviewConfigAdmitsPRLabels(t *testing.T) {
t.Run("empty gate admits every PR", func(t *testing.T) {
var r ReviewConfig
if !r.AdmitsPRLabels(nil) || !r.AdmitsPRLabels([]string{"anything"}) {
t.Fatal("empty review.require_labels must admit every PR")
}
if r.RequireLabelsEnabled() {
t.Fatal("empty gate must report disabled")
}
})
t.Run("blank-only list is the empty gate", func(t *testing.T) {
r := ReviewConfig{RequireLabels: []string{" ", ""}}
if r.RequireLabelsEnabled() || !r.AdmitsPRLabels(nil) {
t.Fatal("blank entries must not turn the gate on")
}
})
t.Run("requires at least one label, case-insensitive exact", func(t *testing.T) {
r := ReviewConfig{RequireLabels: []string{"hive-review", " approved-for-agents "}}
if !r.RequireLabelsEnabled() {
t.Fatal("expected gate on")
}
if r.AdmitsPRLabels(nil) {
t.Fatal("unlabelled PR must be refused")
}
if r.AdmitsPRLabels([]string{"bug", "approved"}) {
t.Fatal("prefix of an approval label must not admit")
}
if !r.AdmitsPRLabels([]string{"bug", "Hive-Review"}) {
t.Fatal("case-insensitive match must admit")
}
if !r.AdmitsPRLabels([]string{"approved-for-agents"}) {
t.Fatal("trimmed configured label must admit")
}
})
t.Run("normalized drops blanks and duplicates", func(t *testing.T) {
r := ReviewConfig{RequireLabels: []string{"a", " a ", "", "B", "b"}}
got := r.NormalizedRequireLabels()
if len(got) != 2 || got[0] != "a" || got[1] != "B" {
t.Fatalf("unexpected normalized labels: %v", got)
}
})
}
6 changes: 6 additions & 0 deletions src/pkg/dashboard/api_config_review.go
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,9 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) {
SelfDecisionPolicy *string `json:"self_authored_decision_policy"`
ConfidenceScore *bool `json:"confidence_score"`
PriorityLabels *bool `json:"priority_labels"`
// RequireLabels replaces review.require_labels whole; an empty list
// turns the PR review label gate off.
RequireLabels *[]string `json:"require_labels"`
// VerdictLabels replaces review.verdict_labels whole: its four keys
// only mean something together (one label per state), and an empty
// object turns the feature off (hivecommons/hive#13833).
Expand Down Expand Up @@ -519,6 +522,9 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) {
if body.PriorityLabels != nil {
cfg.Review.PriorityLabels = *body.PriorityLabels
}
if body.RequireLabels != nil {
cfg.Review.RequireLabels = config.ReviewConfig{RequireLabels: *body.RequireLabels}.NormalizedRequireLabels()
}
if body.MaxReviewsPerHead != nil {
cfg.Review.MaxReviewsPerHead = *body.MaxReviewsPerHead
}
Expand Down
40 changes: 40 additions & 0 deletions src/pkg/dashboard/api_config_review_require_labels_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package dashboard

import (
"net/http"
"testing"
)

// PUT /api/config/review replaces review.require_labels whole, normalizes it,
// and an empty list turns the gate off; an absent key leaves it alone.
func TestReviewConfigPut_RequireLabels(t *testing.T) {
s := covApiServer(t)

rec := doPut(s, "/api/config/review", map[string]any{"require_labels": []string{" hive-review ", "", "hive-review", "approved-for-agents"}})
if rec.Code != http.StatusOK {
t.Fatalf("expected 200, got %d: %s", rec.Code, rec.Body.String())
}
got := s.deps.Config.Review.RequireLabels
if len(got) != 2 || got[0] != "hive-review" || got[1] != "approved-for-agents" {
t.Fatalf("require_labels not normalized: %v", got)
}

if rec := doPut(s, "/api/config/review", map[string]any{"priority_labels": true}); rec.Code != http.StatusOK {
t.Fatalf("expected 200, got %d", rec.Code)
}
if len(s.deps.Config.Review.RequireLabels) != 2 {
t.Fatalf("absent key must leave require_labels untouched: %v", s.deps.Config.Review.RequireLabels)
}

if rec := doPut(s, "/api/config/review", map[string]any{"require_labels": []string{}}); rec.Code != http.StatusOK {
t.Fatalf("expected 200, got %d", rec.Code)
}
if s.deps.Config.Review.RequireLabelsEnabled() {
t.Fatalf("empty list must turn the gate off: %v", s.deps.Config.Review.RequireLabels)
}

get := doGetNoRole(s, "/api/config/review")
if get.Code != http.StatusOK {
t.Fatalf("GET expected 200, got %d", get.Code)
}
}
Loading
Loading