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/fixed-pr-notification-spam.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hive PR notifications no longer spam authors and watchers: the stage stalled/regressed notes, the trusted-human 071 note and the duplicate-PR redirect share one `<!-- hive:status -->` comment per PR that is edited in place instead of appending a comment per event; "**Reviewed** β€” no findings" reviews are recorded as verdicts without a GitHub review and a head carries at most one hive review; the 071 note @-mentions the author once per cause instead of once per head; a check returning to pending after a push is no longer a regression and a merge-train queued/rebasing wait is never stalled. New knob `github.notifications.mode` (`quiet` default, `normal` restores the old behaviour) ([#15875](https://github.com/hivecommons/hive/issues/15875)).
28 changes: 16 additions & 12 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -1969,6 +1969,7 @@ func installReviewRelaySettings(client *github.Client, cfg *config.Config, logge
func() bool { return cfg.Review.CombinedPerspectives },
func() int { return cfg.Review.MaxReviewsPerHead },
)
client.SetNotificationsQuiet(func() bool { return cfg.GitHub.Notifications.Quiet() })
// 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 })
Expand Down Expand Up @@ -2484,18 +2485,21 @@ func planReviewDispatchWith(ctx context.Context, cfg *config.Config, actionable
reviewBotLogins = reviewBots.Logins
}
plan := review.PlanDispatch(prs, artifact, state, review.DispatchOptions{
RequireApproval: cfg.Review.RequireApproval,
FanOut: cfg.Review.FanOut,
MaxParallelReviews: cfg.Review.EffectiveMaxParallelReviews(),
MaxPerspectivesPerPR: cfg.Review.MaxPerspectivesPerPR,
Perspectives: reviewPerspectiveSet(cfg, logger),
CombinedPerspectives: cfg.Review.CombinedPerspectives,
ReviewerAgents: cfg.Review.ReviewerAgents,
FixerAgent: cfg.Review.FixerAgent,
PostComments: cfg.Review.PostComments,
WritingGuideSection: cfg.Project.WritingGuideSection(),
FixHumanPRs: cfg.Review.FixHumanPRsEnabled(),
AcknowledgeNoFindings: cfg.Review.AcknowledgeNoFindings,
RequireApproval: cfg.Review.RequireApproval,
FanOut: cfg.Review.FanOut,
MaxParallelReviews: cfg.Review.EffectiveMaxParallelReviews(),
MaxPerspectivesPerPR: cfg.Review.MaxPerspectivesPerPR,
Perspectives: reviewPerspectiveSet(cfg, logger),
CombinedPerspectives: cfg.Review.CombinedPerspectives,
ReviewerAgents: cfg.Review.ReviewerAgents,
FixerAgent: cfg.Review.FixerAgent,
PostComments: cfg.Review.PostComments,
WritingGuideSection: cfg.Project.WritingGuideSection(),
FixHumanPRs: cfg.Review.FixHumanPRsEnabled(),
// Quiet notification mode never acknowledges a clean review on
// GitHub: the one-liner is an email to everyone to say nothing
// happened, and the verdict is already on the evidence bundle.
AcknowledgeNoFindings: cfg.Review.AcknowledgeNoFindings && !cfg.GitHub.Notifications.Quiet(),
ReviseRepos: cfg.Review.ReviseRepos,
ReviseVerdictsBefore: parseReviseCutoff(cfg.Review.ReviseVerdictsBefore, logger),
PendingTTL: cfg.Review.PendingReviewTTL(),
Expand Down
1 change: 1 addition & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy
ForkGuard: stageForkGuard,
DCORequired: stage.DCO.RequiredFor,
SquashOnly: cfg.AutoMerge.SquashOnlyFor,
QuietNotifications: cfg.GitHub.Notifications.Quiet(),
}
}
}
Expand Down
21 changes: 21 additions & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1116,6 +1116,27 @@ github:
- **Merge.** A PR whose rationale (its closing or referencing links, or the request's declared issue list) traces to an untrusted reporter's issue without any `untrusted_require_labels` acceptance label receives `hold` at **every** ACMM level, including L6, together with a marked notice naming the issue reporter (not the PR author). Any one unaccepted untrusted citation holds. A configured acceptance label supplies maintainer sign-off, so accepted issues do not trigger a new reporter-trust PR hold. A human removes the label; Hive never auto-releases a reporter-trust hold β€” the level-hold release path recognises the notice and leaves the label, and holdguard re-holds on a new head SHA. `github.reporter_trust_hold` follows `reporter_trust.enabled` unless set explicitly; `project.repo_policies[].reporter_trust_hold` overrides per repo; `HIVE_REPORTER_TRUST_HOLD` locks it from the environment, exactly like the #5117 knobs.
- **Where you see it.** Both halves are edited in the dashboard: **Settings β†’ Labels β†’ Reporter trust** (the switch, the association checkboxes, extra logins, triage labels) and **Settings β†’ Repos** (the hold, with the same all-repos default / per-repo override / inherit rows as #5117). An active gate is stated in the read-only note under **Projects**, and each repo card counts issues **needs triage** separately from generic filter refusals. The issue itself carries `needs-triage` while waiting when Hive had to add it. Holds carry the reason in the PR notice and in the `agent_pr_created` audit entry (`reporter_trust_held`, `reporter_login`, `reporter_association`).

### Notification mode: how much of the hive's bookkeeping becomes email

```yaml
github:
notifications:
mode: quiet # default; "normal" posts every note as its own comment/review
```

Every issue comment and every review the hive posts emails the PR author
and every watcher of the repository; editing an existing comment notifies
nobody. In `quiet` mode (the default) the hive's own PR notes β€” stage
stalled/regressed, the trusted-human 071 note, the duplicate-PR redirect β€”
are sections of one `<!-- hive:status -->` comment per PR that is created
once and edited afterwards; a "**Reviewed** β€” no findings" review is
recorded as a verdict without a GitHub review and a head carries at most
one hive review; the 071 note @-mentions the author once per cause rather
than once per head. Nothing is lost: the Activity Monitor, the evidence
bundle and the stage labels carry the same facts. See
[operator-reference.md β†’ Notification mode](operator-reference.md#notification-mode-githubnotificationsmode)
for the full list. `normal` restores the one-comment-per-event behaviour.

### Tracking and archive issues

Some issues are never meant to be worked or closed: a standing report archive that a workflow appends to every week, a long-lived checklist, a "Keep this issue open" status thread. Mark them with **any one** of the label `hive/tracking`, the body marker `<!-- hive:tracking -->`, or the literal sentence "Keep this issue open" in the body, and the hive treats the issue as a tracking issue.
Expand Down
46 changes: 46 additions & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -1215,6 +1215,52 @@ above, and `/api/status` β†’ `writeback.dedupe` carries the settings plus the
last-hour counters `dedupe_same_item`, `dedupe_burst` and `rate_capped`.
`enabled: false` turns the layer off.

### Notification mode (`github.notifications.mode`)

**Why:** every issue comment and every review the hive posts emails the PR
author and everyone watching the repository. Editing an existing comment or
review notifies nobody. Measured on one busy PR, the hive posted eight
comments and three reviews in two hours β€” a 071 note per new head (each
@-mentioning the author), a "stage regressed" note for a check that had
merely gone back to pending after a push, a "stalled" note for a PR that
was simply queued in the merge train, a duplicate-PR redirect, and three
"**Reviewed** β€” no findings" reviews. Multiplied over thirty open PRs that
is dozens of emails an hour saying nothing the Activity Monitor, the
evidence bundle and the stage labels did not already say.

```yaml
github:
notifications:
mode: quiet # quiet (default) | normal
```

`quiet` (the default) changes how the hive delivers its own PR bookkeeping,
not what it records:

- **One status comment per PR, edited in place.** The stage-stalled and
stage-regressed notes, the trusted-human 071 note and the duplicate-PR
redirect are sections of a single comment marked `<!-- hive:status -->`.
The comment is created the first time a note is due and PATCHed for every
later note; only the creation sends email.
- **No "no findings" reviews.** A reviewer whose whole body is the clean
acknowledgement has its verdict recorded through the relay and the
evidence bundle, and no GitHub review is submitted (the reviewer prompts
also stop asking for the line, whatever `review.acknowledge_no_findings`
says). Only perspectives with findings post, and a head carries at most
one hive review: a later perspective's findings for the same head are
folded into the status comment instead of becoming a second review.
- **@-mentions once per cause.** The 071 note mentions the author the first
time a cause class appears (conflict, red CI, changes requested) and is
silent for further heads with the same cause; a new cause mentions again.

Independently of the mode, a check going back to pending after a push is
no longer reported as a stage regression, and a PR the hive itself is
holding β€” queued behind the merge-train front, being rebased by the train,
or waiting on a base refresh β€” is never marked stalled.

`normal` restores the previous behaviour: every note is its own comment,
every perspective's verdict its own review, every new head its own mention.

## Suspicious-activity alerts (`sentinel`)

The sentinel evaluates open PRs in the watched repos β€” human, bot, or agent β€”
Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:4942-4952`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:4969-4979`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes β†’ refactors/docs β†’ tests).
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -3576,6 +3576,11 @@ type GitHubConfig struct {
// reporterTrustHoldEnvOverride is set by HIVE_REPORTER_TRUST_HOLD and never
// serialized, for the same reason as selfAuthorizationHoldEnvOverride.
reporterTrustHoldEnvOverride *bool `yaml:"-" json:"-"`
// Notifications governs how loudly the hive's own PR bookkeeping reaches
// people. Every new issue comment and every review submission emails
// the author and every watcher; editing an existing comment does not.
// See GitHubNotificationsConfig.
Notifications GitHubNotificationsConfig `yaml:"notifications,omitempty" json:"notifications,omitempty"`
// OAuthBaseURLOverride and OAuthAPIURLOverride redirect the DEVICE-FLOW LOGIN
// endpoints away from public github.com. They are a TEST SEAM ONLY β€” see the
// comment on OAuthBaseURL(). They carry the `-` yaml tag so they can never be
Expand Down
43 changes: 43 additions & 0 deletions src/pkg/config/github_notifications.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
package config

import "strings"

// Values for github.notifications.mode.
const (
// NotificationsModeQuiet (the default) folds the hive's own PR
// bookkeeping β€” stage stalled/regressed notes, the trusted-human 071
// note, the duplicate-PR redirect β€” into one status comment per PR that
// is edited in place, posts no "no findings" review, and @-mentions a
// person once per cause rather than once per head.
NotificationsModeQuiet = "quiet"
// NotificationsModeNormal posts every note as its own comment and every
// perspective's verdict as its own review, as the hive did before the
// knob existed.
NotificationsModeNormal = "normal"
)

// GitHubNotificationsConfig is github.notifications: how much of the hive's
// PR bookkeeping becomes an email. Every new issue comment and every review
// submission notifies the author and every watcher of the repository;
// editing an existing comment or review notifies nobody. The Activity
// Monitor, the evidence bundles and the stage labels carry the same facts,
// so the quiet default loses no information.
type GitHubNotificationsConfig struct {
// Mode is "quiet" (default when empty) or "normal".
Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
}

// Quiet reports whether the hive should fold its PR notes into one edited
// status comment and suppress no-findings reviews. Empty reads as quiet.
func (c GitHubNotificationsConfig) Quiet() bool {
return !strings.EqualFold(strings.TrimSpace(c.Mode), NotificationsModeNormal)
}

// Valid reports whether Mode names a known mode (or is unset).
func (c GitHubNotificationsConfig) Valid() bool {
switch strings.ToLower(strings.TrimSpace(c.Mode)) {
case "", NotificationsModeQuiet, NotificationsModeNormal:
return true
}
return false
}
18 changes: 18 additions & 0 deletions src/pkg/config/github_notifications_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
package config

import "testing"

func TestGitHubNotificationsConfig(t *testing.T) {
for mode, quiet := range map[string]bool{"": true, "quiet": true, "Quiet": true, "normal": false, "NORMAL": false} {
c := GitHubNotificationsConfig{Mode: mode}
if !c.Valid() {
t.Errorf("mode %q must be valid", mode)
}
if c.Quiet() != quiet {
t.Errorf("mode %q: Quiet() = %v, want %v", mode, c.Quiet(), quiet)
}
}
if (GitHubNotificationsConfig{Mode: "loud"}).Valid() {
t.Error("unknown mode must be invalid")
}
}
1 change: 1 addition & 0 deletions src/pkg/config/testdata/agent_runtime_golden.json
Original file line number Diff line number Diff line change
Expand Up @@ -435,6 +435,7 @@
"BaseURL": "",
"AppAuthoredPRs": null,
"AppSignedCommits": null,
"notifications": {},
"OAuthBaseURLOverride": "",
"OAuthAPIURLOverride": ""
},
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/config/validate.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package config

import (
Expand Down Expand Up @@ -122,6 +122,9 @@
if c.GitHub.GraphQLPRBatchPageSize < 0 || c.GitHub.GraphQLPRBatchPageSize > 100 {
return fmt.Errorf("github.graphql_pr_batch_page_size must be between 1 and 100, or 0 for the default")
}
if !c.GitHub.Notifications.Valid() {
return fmt.Errorf("github.notifications.mode must be %q or %q", NotificationsModeQuiet, NotificationsModeNormal)
}
if _, err := HeartbeatOmitClasses(c.Hub.HeartbeatOmit); err != nil {
return err
}
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/settings_parity_allowlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@ duplicate_sweep.bot_authors[] # TODO #11854
evidence.complexity.enabled # TODO #11854
evidence.complexity.static_analysis # TODO #11854
github.additional_bot_logins[] # TODO #11854
github.notifications.mode # quiet|normal PR notification mode; yaml-only, see operator-reference.md
github.shared_uid_read_token # shared-UID App read-token opt-in; yaml-only, restart required (#14778)
good_first_issue.exclude_labels[] # advanced scorer tuning; yaml-only (#12185)
good_first_issue.repos[] # advanced scorer tuning; yaml-only (#12185)
Expand Down
33 changes: 27 additions & 6 deletions src/pkg/github/automerge/automerge_contributor_nudge.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"time"

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stagelabels"
)

Expand Down Expand Up @@ -366,9 +367,20 @@ const TrustedHuman071MarkerPrefix = "<!-- hive:human-071-note"
// (conflict / sign-off / failing checks / requested changes) and what the
// hive does next.
func TrustedHuman071Comment(n ContributorNudge, stage stagelabels.Stage) string {
return TrustedHuman071Note(n, stage, true)
}

// TrustedHuman071Note is TrustedHuman071Comment with the @-mention optional:
// in quiet notification mode the author is mentioned once per cause, and a
// re-render for a new head with the same cause names them without the @.
func TrustedHuman071Note(n ContributorNudge, stage stagelabels.Stage, mention bool) string {
var b strings.Builder
fmt.Fprintf(&b, "%s head=%s -->\n", TrustedHuman071MarkerPrefix, n.HeadSHA)
fmt.Fprintf(&b, "@%s this PR is held at `%s` and the hive will not merge it yet.\n\n", n.Author, stage.Label())
at := "@"
if !mention {
at = ""
}
fmt.Fprintf(&b, "%s%s this PR is held at `%s` and the hive will not merge it yet.\n\n", at, n.Author, stage.Label())
if len(n.FailingChecks) > 0 {
b.WriteString("**Failing checks:**\n")
for _, c := range n.FailingChecks {
Expand All @@ -387,7 +399,7 @@ func TrustedHuman071Comment(n ContributorNudge, stage stagelabels.Stage) string

// noteTrustedHuman071 posts TrustedHuman071Comment once per head for a
// trusted human PR in 071. It returns the number of comments posted.
func (c *Engine) noteTrustedHuman071(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, now time.Time) (int, error) {
func (c *Engine) noteTrustedHuman071(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, now time.Time) (int, error) {
rec, ok := store.Get(key)
if !ok || obs.Author == "" || obs.HeadSHA == "" || rec.NudgeHead == obs.HeadSHA {
return 0, nil
Expand All @@ -401,12 +413,21 @@ func (c *Engine) noteTrustedHuman071(ctx context.Context, store *stagelabels.Sto
HeadSHA: obs.HeadSHA, Title: obs.Title, URL: obs.URL, Author: obs.Author, OpenedAt: obs.OpenedAt,
Reason: obs.Reason, FailingChecks: checks, ReviewAsks: asks, HumanChangesRequested: human, Nudge: 1,
}
body := TrustedHuman071Comment(n, stagelabels.NeedsAuthor)
if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
// Normal mode: every head is a fresh comment with a mention. Quiet
// mode: one section of the status comment, rewritten per head, and the
// author is @-mentioned only when the cause changed since the last
// mention β€” a new head failing the same way is the same ask.
mention := !policy.QuietNotifications || rec.MentionDue(obs.Reason)
body := TrustedHuman071Note(n, stagelabels.NeedsAuthor, mention)
posted, err := c.postStageNote(ctx, policy, obs, prstatus.KeyHuman071Note, body)
if err != nil {
c.warn("stage labels: trusted human 071 note failed", "repo", obs.Display, "pr", obs.Number, "error", err)
return 0, err
}
store.MarkNudged(key, obs.HeadSHA, 1, false, now)
c.info("stage labels: trusted human told why the PR is at 071", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "reason", obs.Reason)
return 1, nil
if mention {
store.MarkMentioned(key, obs.Reason)
}
c.info("stage labels: trusted human told why the PR is at 071", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "reason", obs.Reason, "mention", mention)
return posted, nil
}
Loading
Loading