Skip to content
Closed
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/changed-upsert-signoff-unauthorized-nudge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hive no longer posts a new stage-072 contributor nudge on every push to a red contributor-agent PR ([#17067](https://github.com/hivecommons/hive/issues/17067)). On 2026-11-05 the nudge reached 34 comments a day. Each PR now keeps one `hive:contributor-nudge` comment, and its marker carries `reason=<slug>`. A new head that is red for the same reason, or a change of reason, edits that comment in place, which notifies nobody. If the same reason lasts longer than the new `auto_merge.nudge_repeat_after` setting (default `72h`), the hive posts one fresh re-nudge, then goes back to editing. Existing per-head nudge comments are adopted and rewritten in place. The relay `fix-pr` dispatch and the adoption grace are unchanged.
1 change: 1 addition & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy
StalledRequireQuiet: stage.Stalled.IsRequireQuiet(),
ContributorNudge: stage.ContributorNudge.IsEnabled(),
RenudgeInterval: stage.ContributorNudge.EffectiveRenudgeInterval(),
NudgeRepeatAfter: cfg.AutoMerge.EffectiveNudgeRepeatAfter(),
Adoption: stage.Adoption.IsEnabled(),
GraceOnline: stage.EffectiveContributorGraceOnline(),
GraceOffline: stage.EffectiveContributorGraceOffline(),
Expand Down
8 changes: 5 additions & 3 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -1236,9 +1236,11 @@ when the copy is closed without merging (`adopted_by_state` closed /
closed-twice / copy-failed).

A clanker PR entering `stage/072-returned-to-contributor` also triggers the
contributor nudge: the sweep posts one `<!-- hive:contributor-nudge head=…
-->` comment per head naming the failing checks / review asks (re-nudged
once at the stall threshold, cap 2) and hands the diagnosis to the contribute
contributor nudge: the sweep keeps one `<!-- hive:contributor-nudge
reason=… head=… -->` comment per PR naming the failing checks / review asks
(due once per head and once more at the stall threshold, cap 2; a due nudge
edits that comment in place, and a fresh one is posted only once, after the
same reason persisted for `auto_merge.nudge_repeat_after`) and hands the diagnosis to the contribute
hub, which — when the author's relay heartbeat is fresh — pushes a `fix-pr`
interrupt task into their relay session (parallel sub-session or preempt,
per the relay's declared capability) under a per-contributor fix budget;
Expand Down
17 changes: 11 additions & 6 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -753,12 +753,17 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human-
[hive-merge.md](../hive-merge.md#stage-labels)):

1. `stage/072-returned-to-contributor` and ONE `<!-- hive:contributor-nudge
head=<sha> n=<1|2> mode=<comment|queued|spawn|preempt> -->` comment
@-mentioning the author with the failing checks / review asks and "reply
here or push a new head". Re-posted only for a new head; re-nudged once
more after `governor.labels.stage.contributor_nudge.renudge_interval`
(default = the stage's 24h dwell, i.e. at `stage/stalled`), then no more
— **cap: 2 nudges per head**. `mode=` records how the relay side was
reason=<slug> head=<sha> n=<1|2> mode=<comment|queued|spawn|preempt>
since=<time> repeat=<0|1> -->` comment per PR @-mentioning the author with
the failing checks / review asks and "reply here or push a new head". The
nudge is due once per head and once more after
`governor.labels.stage.contributor_nudge.renudge_interval` (default = the
stage's 24h dwell, i.e. at `stage/stalled`) — **cap: 2 nudges per head** —
but a due nudge edits the existing comment in place (a new head red for the
same reason, or a changed reason) instead of posting another copy
(hivecommons/hive#17067). While the same reason persists past
`auto_merge.nudge_repeat_after` (default 72h) the hive posts one fresh
re-nudge, then only edits. `mode=` records how the relay side was
handled so the comment itself answers "did their agent get interrupted?".
`governor.labels.stage.contributor_nudge.enabled: false` turns the
comment and the relay task off; the stage label still moves.
Expand Down
1 change: 1 addition & 0 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -471,6 +471,7 @@ advanced into the merge path.
| `auto_merge.self_authored` | **on** when unset | The only off switch. `false` disables the sweep and App-authored PRs fall back to fully manual merges. |
| `auto_merge.max_merges` | `3` (`DefaultAutoMergeSweepMaxMerges`) when 0/unset | Caps merges per sweep pass. |
| `auto_merge.min_head_age` | `3m` | Minimum PR head age before automerge trusts an unknown required-check set. A fresh head pushed more recently than this waits with `pending: head pushed ... ago (< min_head_age)` unless `auto_merge.required_checks` is declared and every required check is complete and successful. Head age is measured from the head commit's committer date (never earlier than the PR's creation), not the PR's `updated_at`, so label and comment activity — including the hive's own — does not restart it. When GitHub's head time is ahead of the host clock (clock skew), age is measured from when the hive first observed the head instead, so the hold lasts one window and then clears (`pending: head time ahead of host clock; head first seen ... ago (< min_head_age)`). |
| `auto_merge.nudge_repeat_after` | `72h` | How long the same stage-072 contributor-nudge reason must persist before the hive posts its single fresh re-nudge comment. Otherwise each PR keeps one `hive:contributor-nudge` comment: a new head red for the same reason, or a changed reason, edits it in place (which notifies nobody) instead of posting another copy. After the one re-nudge the hive only edits. The relay `fix-pr` dispatch and the adoption grace are not affected (#17067). |
| `auto_merge.required_checks` | unset | Default operator-declared status-check contexts / check-run names (e.g. `["build-gate"]`) that the sweep's green gate requires on repos without a per-repo override. See below. |
| `auto_merge.repos.<repo>.required_checks` | inherits default | Per-repo override for heterogeneous hives. `<repo>` may be the bare name from `project.repos` or `owner/repo`; an explicit empty list declares that GitHub has no required contexts, while Hive still requires positive CI evidence from at least one real successful check-run before merge. |
| `auto_merge.allow_unprotected_base` | deprecated no-op | Accepted for compatibility only. [`hive-merge`](../hive-merge.md) no longer refuses solely because a base branch has no GitHub branch protection; it may merge into any branch the App can write after positive CI evidence. |
Expand Down
9 changes: 6 additions & 3 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,12 @@ on; `governor.labels.stage.enabled: false` stops the reconciler,
`governor.labels.stage.stalled.require_quiet: false` measures the dwell from
stage entry instead of last activity (Settings → Labels). When a clanker
PR enters
`stage/072-returned-to-contributor` the hive posts one nudge comment per head
(re-nudged once after `governor.labels.stage.contributor_nudge.renudge_interval`,
default = the 24h dwell; cap 2) and, for a contributor whose relay heartbeat is
`stage/072-returned-to-contributor` the hive nudges once per head
(again once after `governor.labels.stage.contributor_nudge.renudge_interval`,
default = the 24h dwell; cap 2) through one `hive:contributor-nudge` comment
per PR that a new head or reason edits in place; a fresh comment is posted
again only once, after the same reason persisted for `auto_merge.nudge_repeat_after`
(default 72h). For a contributor whose relay heartbeat is
within `governor.labels.stage.presence_window` (default 15m), pushes a `fix-pr`
interrupt to their relay session, bounded by the per-contributor fix budget
(`contribute.max_parallel_fixes` / `contribute.min_focus_window`).
Expand Down
20 changes: 20 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -8322,6 +8322,12 @@ type AutoMergeConfig struct {
// GitHub Actions check-runs have not registered yet. Non-positive values
// use DefaultAutoMergeMinHeadAge.
MinHeadAge time.Duration `yaml:"min_head_age,omitempty" json:"min_head_age,omitempty"`
// NudgeRepeatAfter is how long the same stage-072 contributor-nudge
// reason must persist before the hive posts its single fresh re-nudge
// (hivecommons/hive#17067); until then, and after it, the PR's one nudge
// comment is edited in place. Non-positive values use
// DefaultAutoMergeNudgeRepeatAfter.
NudgeRepeatAfter time.Duration `yaml:"nudge_repeat_after,omitempty" json:"nudge_repeat_after,omitempty"`
// RequiredChecks is the default operator-declared list of status-check
// contexts/check-run names that the self-merge sweep's commitGreen must
// gate on for repos without an auto_merge.repos.<repo>.required_checks
Expand Down Expand Up @@ -8893,6 +8899,11 @@ func (c ContributorTierAutoMergeConfig) Validate() error {
// when auto_merge.min_head_age is unset.
const DefaultAutoMergeMinHeadAge = 3 * time.Minute

// DefaultAutoMergeNudgeRepeatAfter is auto_merge.nudge_repeat_after's
// default: one fresh contributor re-nudge after three days of the same
// reason, then only in-place edits.
const DefaultAutoMergeNudgeRepeatAfter = 72 * time.Hour

// DefaultTrustedBotAuthors is the TrustedBotAuthors value when the operator
// declares none. Only dependabot: its PRs are single-dependency bumps whose
// safety is entirely established by the repo's own CI, which the sweep gates on.
Expand Down Expand Up @@ -9192,6 +9203,15 @@ func (a AutoMergeConfig) EffectiveMinHeadAge() time.Duration {
return DefaultAutoMergeMinHeadAge
}

// EffectiveNudgeRepeatAfter returns NudgeRepeatAfter, or
// DefaultAutoMergeNudgeRepeatAfter when it is unset or non-positive.
func (a AutoMergeConfig) EffectiveNudgeRepeatAfter() time.Duration {
if a.NudgeRepeatAfter > 0 {
return a.NudgeRepeatAfter
}
return DefaultAutoMergeNudgeRepeatAfter
}

// SelfAuthoredEnabled reports whether the App-self-merge sweep is on for this
// hive. Default ON (nil == enabled): see AutoMergeConfig.SelfAuthored.
func (a AutoMergeConfig) SelfAuthoredEnabled() bool {
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 @@ -168,6 +168,7 @@ auto_merge.native_merge_queue.repos[] # native merge queue per-repo allow-list (
auto_merge.native_merge_queue.skip_current_base_gate # explicit current-base bypass on queue bases (#15198); yaml-only
auto_merge.hive_superseding.auto_merge # hive-authored superseding PRs auto-merge without an operator decision; yaml-only
auto_merge.no_ci_ok[] # TODO #11854
auto_merge.nudge_repeat_after # one contributor re-nudge per persisting reason (#17067); yaml-only
auto_merge.repos.<key>.required_checks[] # TODO #11854
auto_merge.require_current_base[] # current-base gate per-repo "on" override, written by the Repos tab (#15335)
auto_merge.required_checks[] # TODO #11854
Expand Down
163 changes: 155 additions & 8 deletions src/pkg/github/automerge/automerge_contributor_nudge.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/advisory"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stagelabels"
)
Expand All @@ -23,6 +24,13 @@ import (
// diagnosis to the author's relay session as a fix-pr task. It re-nudges once
// more at the stall threshold and then stops: 2 nudges per head, re-armed
// only when the author pushes a new head.
//
// The GitHub side is one comment per PR (hivecommons/hive#17067): a nudge
// that is due edits the hive's existing nudge comment in place when a new
// head is red for the same reason or the reason changed, and a fresh comment
// is posted again only once, after the same reason persisted for
// auto_merge.nudge_repeat_after. The relay fix-pr dispatch and the adoption
// grace ledger still run on every due nudge.

// ContributorNudgeMarkerPrefix opens the nudge comment's machine marker.
const ContributorNudgeMarkerPrefix = "<!-- hive:contributor-nudge"
Expand Down Expand Up @@ -196,11 +204,89 @@ func nudgeDiagnosisRouted(reason string, d stageDetail, route *stagelabels.Route
}

// ContributorNudgeComment renders the nudge comment. The marker carries the
// head, the nudge ordinal and the delivery mode so a later pass can prove the
// comment exists without a per-PR GET.
// reason, the head, the nudge ordinal and the delivery mode so a later pass
// can prove the comment exists without a per-PR GET.
func ContributorNudgeComment(n ContributorNudge, out ContributorNudgeOutcome) string {
return contributorNudgeBody(n, out, contributorNudgeMarker{})
}

// contributorNudgeMarker is what the nudge comment's marker records beyond
// the nudge itself (hivecommons/hive#17067).
type contributorNudgeMarker struct {
// Reason is the reason slug the comment was rendered for.
Reason string
Head string
// Since is when the hive first nudged for Reason on this PR; zero when
// unknown (a legacy marker).
Since time.Time
// Repeat is 1 once the single fresh re-nudge for Reason was posted.
Repeat int
}

// nudgeReasonSlug turns a lane reason into the marker's reason= token:
// lower case, no spaces, nothing that could close the HTML comment.
func nudgeReasonSlug(reason string) string {
var b strings.Builder
for _, r := range strings.ToLower(strings.TrimSpace(reason)) {
switch {
case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == ':', r == '.', r == '_', r == '/':
b.WriteRune(r)
default:
b.WriteByte('-')
}
}
slug := b.String()
for strings.Contains(slug, "--") {
slug = strings.ReplaceAll(slug, "--", "-")
}
slug = strings.Trim(slug, "-")
if len(slug) > 80 {
slug = strings.TrimRight(slug[:80], "-")
}
if slug == "" {
return "unknown"
}
return slug
}

// parseContributorNudgeMarker reads the marker line opening body; legacy
// per-head markers parse with an empty Reason.
func parseContributorNudgeMarker(body string) (contributorNudgeMarker, bool) {
line, _, _ := strings.Cut(body, "\n")
line = strings.TrimSpace(line)
if !strings.HasPrefix(line, ContributorNudgeMarkerPrefix+" ") || !strings.HasSuffix(line, "-->") {
return contributorNudgeMarker{}, false
}
var m contributorNudgeMarker
for _, field := range strings.Fields(strings.TrimSuffix(strings.TrimPrefix(line, ContributorNudgeMarkerPrefix), "-->")) {
key, value, _ := strings.Cut(field, "=")
switch key {
case "reason":
m.Reason = value
case "head":
m.Head = value
case "since":
if t, err := time.Parse(time.RFC3339, value); err == nil {
m.Since = t
}
case "repeat":
if value == "1" {
m.Repeat = 1
}
}
}
return m, true
}

// contributorNudgeBody renders the nudge comment with the upsert state in
// its marker.
func contributorNudgeBody(n ContributorNudge, out ContributorNudgeOutcome, m contributorNudgeMarker) string {
var b strings.Builder
fmt.Fprintf(&b, "%s head=%s n=%d mode=%s -->\n", ContributorNudgeMarkerPrefix, n.HeadSHA, n.Nudge, nonEmpty(out.Mode, "comment"))
fmt.Fprintf(&b, "%s reason=%s head=%s n=%d mode=%s", ContributorNudgeMarkerPrefix, nudgeReasonSlug(n.Reason), n.HeadSHA, n.Nudge, nonEmpty(out.Mode, "comment"))
if !m.Since.IsZero() {
fmt.Fprintf(&b, " since=%s repeat=%d", m.Since.UTC().Format(time.RFC3339), m.Repeat)
}
b.WriteString(" -->\n")
if n.Stalled {
fmt.Fprintf(&b, "@%s this PR has been waiting on you for a while (`%s`). ", n.Author, stagelabels.ReturnedToContributor.Label())
} else {
Expand Down Expand Up @@ -305,17 +391,78 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store,
if c.contributorNudge != nil {
out = c.contributorNudge.Nudge(ctx, n)
}
body := ContributorNudgeComment(n, out)
if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "error", err)
posted, action, err := c.upsertContributorNudge(ctx, obs, n, out, policy, now)
if err != nil {
c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "action", action, "error", err)
return 0, err
}
// "queued" only says the author has a relay registered here; the work
// sits in its queue whether or not that relay is connected. Counting it
// as online gave an offline clanker the 2h online grace (#15566).
store.MarkNudged(key, obs.HeadSHA, ordinal, out.Online || out.Mode == "spawn" || out.Mode == "preempt", now)
c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason)
return 1, nil
c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason, "comment", action)
return posted, nil
}

// upsertContributorNudge writes the GitHub side of a due nudge
// (hivecommons/hive#17067): the first nudge on a PR posts the comment; a
// later one edits the hive's latest nudge comment in place, whether the
// head moved or the reason changed; and once the same reason has persisted
// for auto_merge.nudge_repeat_after the hive posts one fresh re-nudge, then
// only edits again. It returns the comments posted and what it did
// ("posted", "repeated", "edited", "unchanged").
func (c *Engine) upsertContributorNudge(ctx context.Context, obs stageObservation, n ContributorNudge, out ContributorNudgeOutcome, policy StageLabelPolicy, now time.Time) (int, string, error) {
repeatAfter := policy.NudgeRepeatAfter
if repeatAfter <= 0 {
repeatAfter = config.DefaultAutoMergeNudgeRepeatAfter
}
slug := nudgeReasonSlug(n.Reason)
existing, prev := c.latestOwnContributorNudge(ctx, obs)
next := contributorNudgeMarker{Reason: slug, Since: now}
action := "posted"
if existing != nil {
if prev.Reason == slug && !prev.Since.IsZero() {
next.Since, next.Repeat = prev.Since, prev.Repeat
}
if prev.Reason == slug && prev.Repeat == 0 && !prev.Since.IsZero() && now.Sub(prev.Since) >= repeatAfter {
next.Repeat = 1
existing = nil
action = "repeated"
}
}
body := contributorNudgeBody(n, out, next)
if existing != nil {
if body == existing.GetBody() {
return 0, "unchanged", nil
}
if err := c.editMarkerComment(ctx, obs.Owner, obs.Repo, existing.GetID(), body); err != nil {
return 0, "edited", err
}
return 0, "edited", nil
}
if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
return 0, action, err
}
return 1, action, nil
}

// latestOwnContributorNudge returns the hive's most recent nudge comment on
// the PR and its marker, or nil. A list failure reads as "none", so the
// nudge is posted rather than lost.
func (c *Engine) latestOwnContributorNudge(ctx context.Context, obs stageObservation) (*gh.IssueComment, contributorNudgeMarker) {
existing, err := c.findOwnMarkerComment(ctx, obs.Owner, obs.Repo, obs.Number, func(body string) bool {
_, ok := parseContributorNudgeMarker(body)
return ok
})
if err != nil {
c.warn("stage labels: could not list comments for the nudge upsert", "repo", obs.Display, "pr", obs.Number, "error", err)
return nil, contributorNudgeMarker{}
}
if existing == nil {
return nil, contributorNudgeMarker{}
}
marker, _ := parseContributorNudgeMarker(existing.GetBody())
return existing, marker
}

// withoutForkGuard drops the fork-guard checks from a nudge's failing
Expand Down
Loading
Loading