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-adoption-skips-repo-maintainers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Contributor adoption (stage `074` and its re-home / DCO re-home) no longer takes over a PR whose author has admin or maintain permission on the repository: a repo admin's PR was adopted as "contributor-offline" 16 minutes after its nudge and then closed in favour of a hive copy. The permission is read once per repository and author per hour, a failed read does not adopt, and an existing in-place adoption of such an author is released.
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ referenced it) a lone `stage/050-review-pending`
| `stage/070-fixing` | PR | hive-owned repair: App/taken-over PR red, changes requested (by the swarm, or by a trusted human's **changes requested** review / `/hive decision <text>` on the current head — reason `human-changes-requested`, which also kicks the author agent with the text verbatim, [#13041](https://github.com/hivecommons/hive/issues/13041)) or needs-rebase, **or** a non-App PR whose red head was caused by a hive-pushed commit that must be removed/re-homed; a hive agent is reworking it | 2h |
| `stage/071-needs-author` | PR | human-authored PR (`author/human`): CI red / changes requested / conflicting; the hive posted its diagnosis, the author must act. No nudge, no adoption — the person pushes or comments | 24h |
| `stage/072-returned-to-contributor` | PR | clanker PR (`author/clanker`, relay or external hive): CI red / changes requested / conflicting; the hive posted its diagnosis, the ball is in the contributor hive's court. (Briefly spelled `stage/072-needs-author` by [#12713](https://github.com/hivecommons/hive/pull/12713); the engine renames that label back in place) | 24h |
| `stage/074-adopted-by-hive` | PR | the author (a clanker) was unavailable — relay offline, never registered, or silent past the grace (see below); the hive took the PR over: in place on the PR's own branch when it may push there (the scanner's red-PR fix kick rebases and fixes it), otherwise via `hive/adopt-<n>` and a superseding App PR that keeps the author's commits (the original closes automatically when the superseder merges). Adoption is an **ownership** state, not a CI state: the PR reads 074 for as long as the hive owns it — through its fixes going pending, green, reviewed or red again (074 outranks 050/060/070/071/072) — and leaves 074 only at the merge gate (080/085/090/100), when the adoption is released, or to 085 `adoption-stalled:<reason>` when the head sat unchanged past the dwell with CI idle and a real blocker the hive cannot push past — a red optional check alone never counts, and the escalation releases back to 074 as soon as the reason clears (an in-place adoption with a blocking review finding re-homes to `hive/adopt-<n>` first instead; one with a squash-unsafe hive commit elects a merge commit on a `role/trusted` PR — `merge-method/merge` label, lane continues — and otherwise goes to 085 `adoption-stalled:hive-signoff-attribution` at once, without a supersede, naming why the election was refused). For in-place adoption, a changed head must be linked to the App bot by GitHub commit metadata (the stage store only remembers heads that already passed that check); otherwise the hive treats it as a contributor push and hands the PR back (072 if red, else the normal path). Forgeable git author/committer names and emails never keep 074. | 3h |
| `stage/074-adopted-by-hive` | PR | the author (a clanker) was unavailable — relay offline, never registered, or silent past the grace (see below); the hive took the PR over: in place on the PR's own branch when it may push there (the scanner's red-PR fix kick rebases and fixes it), otherwise via `hive/adopt-<n>` and a superseding App PR that keeps the author's commits (the original closes automatically when the superseder merges). Adoption is an **ownership** state, not a CI state: the PR reads 074 for as long as the hive owns it — through its fixes going pending, green, reviewed or red again (074 outranks 050/060/070/071/072) — and leaves 074 only at the merge gate (080/085/090/100), when the adoption is released, or to 085 `adoption-stalled:<reason>` when the head sat unchanged past the dwell with CI idle and a real blocker the hive cannot push past — a red optional check alone never counts, and the escalation releases back to 074 as soon as the reason clears (an in-place adoption with a blocking review finding re-homes to `hive/adopt-<n>` first instead; one with a squash-unsafe hive commit elects a merge commit on a `role/trusted` PR — `merge-method/merge` label, lane continues — and otherwise goes to 085 `adoption-stalled:hive-signoff-attribution` at once, without a supersede, naming why the election was refused). For in-place adoption, a changed head must be linked to the App bot by GitHub commit metadata (the stage store only remembers heads that already passed that check); otherwise the hive treats it as a contributor push and hands the PR back (072 if red, else the normal path). Forgeable git author/committer names and emails never keep 074. A PR whose author holds **admin** or **maintain** on the repository is never adopted or re-homed (one cached permission read per repo and author per hour; a failed read does not adopt), and an in-place adoption of such an author is released on the next pass. | 3h |
| `stage/080-awaiting-merge-admission` | PR | nothing left for the author: CI green (no red check on the head, required or not), verdict approve, no modifiers — and the automerge lane has not admitted it yet (prefilter not evaluated for this head, labels not synced, lane tripped). A stall here means a lane problem, so the hive also posts one `<!-- hive:stage-stalled -->` comment with the lane's last skip reason | 30m |
| `stage/085-needs-decision` | PR | **PR-only** since the owner decision of 2026-10-17 (issues park at `stage/045-needs-decision`; before that this stage carried both, [#12683](https://github.com/hivecommons/hive/issues/12683)). A person owes a **decision**, not a merge: a `requires_human` swarm verdict (reason `reviewer-verdict:requires_human`), `sentinel-alert`, `hold` / `do-not-merge*` / `needs-decision` modifier, no reviewer configured, GitHub workflow approval is required for a trusted same-repo bot/App/clanker PR (`workflow-approval-required:<ctx>`); Hive has posted `/ok-to-test` and is waiting for the repo-local `hive-ok-to-test` workflow or a maintainer, or a human-only lane rule unrelated to trust (workflow-path edits, tests removed, human-merge path, reporter-trust hold), or an open issue the PR closes is held or parked (`linked-issue:hold:#N:<label>` / `linked-issue:needs-decision:#N:<label>`), or GitHub refused to update the branch from its base because the base changed `.github/workflows/` and the App lacks the workflows permission (`workflow-permission`: a person merges or rebases the base in and pushes, or grants the App Workflows: write). A trusted human's normal GitHub **Approve** review on the exact current head clears a `requires_human` verdict for any author kind/lane and records `reviewer-verdict:requires_human:human-approved@<login>`; a new head invalidates it. The same approval also clears the merge-lane review gate over any non-approved swarm outcome, a perspective's `changes_requested` included (the `review_evaluated` audit line records `human_approver` and `overrode`); without it, `changes_requested` / `reject` still require fixes or manual merge. Under `review.self_authored_decision_policy: resolve`, a Hive-authored PR's reviewer decision question parks here only when it matches a named risk class (`review.DecisionRiskClasses`: permissions/credentials, security, sensitive paths, data loss/irreversible, merge/trust policy, external side effects, licensing/legal, unverifiable) or carries `<!-- hive-decision-risk: high -->`; any other question is resolved by policy and recorded as an advisory reason on the approving aggregate. Hive-authored non-risk incomplete-fix reviews with concrete remediation are normalized to `changes_requested` at verdict load/aggregation time and by the stage-label detail selector, even when the finding was marked high severity; duplicate summary/changelog intent-alignment cleanup with a concrete trim/reword fix is included. Those PRs go to `stage/070-fixing`, not here. On a hive-authored PR the trusted human can also answer with a **changes requested** review on the head, or `/hive decision <what to change>`, which moves the PR to `stage/070-fixing` and kicks the author agent with the text verbatim ([#13041](https://github.com/hivecommons/hive/issues/13041)); `/hive decision` on a PR the hive did not open gets one reply naming the review-side equivalents. One `<!-- hive:stage-needs-decision -->` comment on entry names what is owed and, per lane, what clears it ([#13087](https://github.com/hivecommons/hive/issues/13087)): for a hive-authored `requires_human` park the two actions — approve the head (review or `/hive approve` reply after the verdict) to merge as-is, or request changes and the hive pushes the fix; for any other `requires_human` park a trusted merger's approval by review or `/hive approve` reply; for a hold / sentinel park the label a person must remove; for a linked-issue park the issue and the label to remove from it; and for a manual-merge-only lane rule that a maintainer must merge by hand, which no approval overrides | none |
| `stage/090-ready-for-human-merge` | PR | the hive would merge this itself but trust/role blocks it: reviewer verdict approve at the **current** head, required checks green (tide excluded), DCO yes, no sentinel alert, no conflicts, soak elapsed, no hold — and the only remaining lane reason is the author's tier/role. A maintainer's `/lgtm` `/approve` is the only missing step. One `<!-- hive:stage-ready-for-human-merge -->` comment on entry carries the evidence. Always read with the `role/*` and `author/*` labels. (Was `stage/090-needs-human` before [#12528](https://github.com/hivecommons/hive/issues/12528); the engine renames the GitHub label in place) | none |
Expand Down
112 changes: 112 additions & 0 deletions src/pkg/github/automerge/automerge_adopt_maintainer_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
package automerge

import (
"testing"
"time"

"github.com/hivecommons/hive/pkg/stagelabels"
)

// projectbluefin/utah-packages#619: the author was a repository admin. The
// hive nudged the PR at 072, adopted it as contributor-offline 16 minutes
// later and then re-homed it, closing the admin's own PR. Adoption stands in
// for a quiet contributor relay, never for a maintainer.

func TestRepoMaintainerLevel(t *testing.T) {
for _, tc := range []struct {
permission, role string
want bool
}{
{"admin", "admin", true},
{"write", "maintain", true},
{"ADMIN", "", true},
{"write", "write", false},
{"write", "triage", false},
{"read", "read", false},
{"none", "", false},
} {
if got := repoMaintainerLevel(tc.permission, tc.role); got != tc.want {
t.Errorf("repoMaintainerLevel(%q, %q) = %v, want %v", tc.permission, tc.role, got, tc.want)
}
}
}

func TestAdoptionSkipsRepositoryMaintainer(t *testing.T) {
for _, role := range []string{"admin", "maintain"} {
t.Run(role, func(t *testing.T) {
p := adoptPolicy()
p.AdoptInPlace = true
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "comment"}, p)
defer done()
h.adopt.permissions = map[string]string{"mallory": role}
h.adopt.allowMaintainerEdits(7, true)
h.observe(adoptPR(7, "aaa"), "check-failing:unit")
labels := []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"}
// Past the grace, then two more sweeps inside one cache window.
for _, step := range []time.Duration{2 * time.Hour, 10 * time.Minute, 10 * time.Minute} {
h.clock.advance(step)
h.observe(adoptPR(7, "aaa", labels...), "check-failing:unit")
}
if n := adoptionComments(h.api); len(n) != 0 || len(h.adopt.pulls) != 0 || len(h.adopt.refs) != 0 {
t.Fatalf("maintainer's PR adopted: comments=%v pulls=%v refs=%v", n, h.adopt.pulls, h.adopt.refs)
}
rec, _ := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7))
if rec.Stage != stagelabels.ReturnedToContributor || rec.AdoptedHead != "" {
t.Fatalf("record: %+v", rec)
}
if h.adopt.permissionReads != 1 {
t.Fatalf("permission read %d times, want 1 (cached)", h.adopt.permissionReads)
}
})
}
}

func TestAdoptionFailsClosedOnPermissionError(t *testing.T) {
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "comment"}, adoptPolicy())
defer done()
h.adopt.failPermission = true
h.observe(adoptPR(7, "aaa"), "check-failing:unit")
h.clock.advance(2 * time.Hour)
h.observe(adoptPR(7, "aaa", "stage/072-returned-to-contributor", "role/contributor", "author/clanker"), "check-failing:unit")
if len(adoptionComments(h.api)) != 0 || len(h.adopt.pulls) != 0 {
t.Fatalf("adopted although the permission read failed: %v", h.api.comments)
}
// The error is not cached: once the read works, a write-level author
// is adopted as before.
h.adopt.failPermission = false
h.clock.advance(time.Minute)
h.observe(adoptPR(7, "aaa", "stage/072-returned-to-contributor", "role/contributor", "author/clanker"), "check-failing:unit")
if len(adoptionComments(h.api)) != 1 {
t.Fatalf("write-level author not adopted after the read recovered: %v", h.api.comments)
}
}

// An in-place adoption taken before the author was known to maintain the
// repository is released on the next pass and never re-homed.
func TestInPlaceAdoptionOfMaintainerIsReleased(t *testing.T) {
p := adoptPolicy()
p.AdoptInPlace = true
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "comment"}, p)
defer done()
h.adopt.allowMaintainerEdits(7, true)
h.observe(adoptPR(7, "aaa"), "check-failing:unit")
labels := []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"}
h.clock.advance(30 * time.Minute)
h.observe(adoptPR(7, "aaa", labels...), "check-failing:unit")
if rec, _ := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7)); !rec.AdoptedInPlace() {
t.Fatalf("setup: not adopted in place: %+v", rec)
}

// The author is (now) an admin; the cached write-level answer expires.
h.adopt.permissions = map[string]string{"mallory": "admin"}
h.clock.advance(maintainerPermTTL + time.Minute)
h.api.reset()
h.observe(adoptPR(7, "aaa", "stage/074-adopted-by-hive", "role/contributor", "author/clanker"), "check-failing:unit")
rec, _ := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7))
if rec.AdoptedHead != "" || rec.Stage == stagelabels.AdoptedByHive {
t.Fatalf("maintainer's in-place adoption kept: %+v", rec)
}
if len(h.adopt.pulls) != 0 || len(h.adopt.refs) != 0 {
t.Fatalf("maintainer's PR re-homed: pulls=%v refs=%v", h.adopt.pulls, h.adopt.refs)
}
}
66 changes: 66 additions & 0 deletions src/pkg/github/automerge/automerge_contributor_adopt.go
Original file line number Diff line number Diff line change
Expand Up @@ -562,6 +562,10 @@ func (c *Engine) adoptContributorPR(ctx context.Context, store *stagelabels.Stor
c.info("stage labels: adoption due but blocked by label", "repo", obs.Display, "pr", obs.Number, "label", l)
return 0, nil
}
if c.authorMaintainsRepo(ctx, obs, now) {
c.info("stage labels: adoption due but the author maintains the repository; not adopting", "repo", obs.Display, "pr", obs.Number, "author", obs.Author)
return 0, nil
}
fence, err := c.adoptionDiffRefusal(ctx, obs)
if fence != "" && (err != nil || adoptionFenceDefers(fence)) {
// The fence could not judge this head (it moved, or its file list
Expand Down Expand Up @@ -608,6 +612,13 @@ func (c *Engine) adoptContributorPR(ctx context.Context, store *stagelabels.Stor
}

func (c *Engine) supersedeAdoptedPR(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, rec stagelabels.Record, policy StageLabelPolicy, reason string, grace time.Duration, online bool, dcoRehome bool, now time.Time) (int, error) {
if c.authorMaintainsRepo(ctx, obs, now) {
// Backstop for every re-home path (dco-rehome, in-place-stalled):
// a maintainer's PR is never closed in favour of a hive copy.
store.ClearAdoption(key)
c.info("stage labels: not superseding a repository maintainer's PR; adoption released", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "reason", reason)
return 0, nil
}
owner, repo, number := obs.Owner, obs.Repo, obs.Number
rec.AdoptReason = reason
if stored, ok := store.Get(key); ok && stored.AdoptDiffFence != "" {
Expand Down Expand Up @@ -751,6 +762,54 @@ func (c *Engine) settleAdoption(ctx context.Context, store *stagelabels.Store, k
return 0, nil
}

// maintainerPermTTL is how long authorMaintainsRepo trusts a permission
// read: one GET per (repo, author) per hour, not per PR per sweep.
const maintainerPermTTL = time.Hour

type maintainerPermEntry struct {
maintainer bool
at time.Time
}

// repoMaintainerLevel reports whether a collaborator permission answer
// (`permission`, and the finer `role_name`) is admin or maintain.
func repoMaintainerLevel(permission, role string) bool {
permission, role = strings.ToLower(strings.TrimSpace(permission)), strings.ToLower(strings.TrimSpace(role))
return permission == "admin" || role == "admin" || role == "maintain"
}

// authorMaintainsRepo reports whether the PR author holds admin or maintain
// on the PR's repository. Adoption stands in for a contributor's relay that
// went quiet; a maintainer owns the branch and merges it themselves, so the
// hive never takes their PR over (projectbluefin/utah-packages#619, adopted
// as contributor-offline 16 minutes after its nudge and re-homed). A failed
// read is not cached and counts as a maintainer: adoption fails closed.
func (c *Engine) authorMaintainsRepo(ctx context.Context, obs stageObservation, now time.Time) bool {
if c == nil || c.gh == nil || obs.Author == "" || obs.Owner == "" || obs.Repo == "" {
return false
}
key := strings.ToLower(obs.Owner + "/" + obs.Repo + "#" + obs.Author)
c.maintainerPermMu.Lock()
if e, ok := c.maintainerPerm[key]; ok && now.Sub(e.at) < maintainerPermTTL {
c.maintainerPermMu.Unlock()
return e.maintainer
}
c.maintainerPermMu.Unlock()
level, _, err := c.gh.Repositories.GetPermissionLevel(ctx, obs.Owner, obs.Repo, obs.Author)
if err != nil {
c.warn("stage labels: could not read the author's repository permission; not adopting", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "error", err)
return true
}
maintainer := repoMaintainerLevel(level.GetPermission(), level.GetRoleName())
c.maintainerPermMu.Lock()
if c.maintainerPerm == nil {
c.maintainerPerm = map[string]maintainerPermEntry{}
}
c.maintainerPerm[key] = maintainerPermEntry{maintainer: maintainer, at: now}
c.maintainerPermMu.Unlock()
return maintainer
}

// canPushToPRBranch reports whether the App can push to the PR's head: a
// head in the base repo always; a fork head only with "allow edits by
// maintainers", which the list payload omits, so one GET resolves it.
Expand Down Expand Up @@ -814,6 +873,13 @@ func (c *Engine) baseSyncTouchesWorkflows(ctx context.Context, obs stageObservat
// re-arms.
// Returns the number of comments posted.
func (c *Engine) settleInPlaceAdoption(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, prev stagelabels.Record, policy StageLabelPolicy) (int, error) {
if prev.AdoptedInPlace() && c.authorMaintainsRepo(ctx, obs, c.now()) {
// Taken over before this rule, or before the author's permission
// was raised: hand the PR back rather than keep or re-home it.
store.ClearAdoption(key)
c.info("stage labels: in-place adoption of a repository maintainer's PR released", "repo", obs.Display, "pr", obs.Number, "author", obs.Author)
return 0, nil
}
if !prev.AdoptedInPlace() || obs.HeadSHA == "" || obs.HeadSHA == prev.AdoptedHead {
return 0, nil
}
Expand Down
Loading
Loading