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-085-ask-matches-workflow-fence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `stage/085-needs-decision` notes no longer contradict each other on a PR that edits CI workflow files (projectbluefin/testsuite#1037): when a trusted merger's approval releases the `contributor-lane:workflow-path` fence ([#14664](https://github.com/hivecommons/hive/issues/14664)), the entry comment's **What to do** asks for that GitHub **Approve** review instead of saying no approval helps, and still lists the sentinel alert and hold labels to clear; when the lane never merges the head unattended (tests removed, human-merge path, or a workflow fence the approval cannot release), the sign-off attribution and adoption-stalled notes offer only the by-hand merge with a merge commit and name the rule, and an open sentinel alert is named in them too.
5 changes: 4 additions & 1 deletion src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -556,7 +556,10 @@ A PR merges through this tier only when all of the following hold:
attributed to the maintainer and bound to the head) or a trusted merger's
own `/hive decision approve` comment posted after the head. Approval on an
earlier head never counts: a new push re-arms the fence and the 085 note
reads "awaiting owner approval … re-approve after a push". When released
reads "awaiting owner approval … re-approve after a push"; its **What to
do** asks for that review (a `/hive approve` reply does not release the
fence) and still lists a sentinel alert or hold label a person must clear
(projectbluefin/testsuite#1037). When released
the lane logs `workflow-path fence released by owner approval login=…
head=…`, leaves one `<!-- hive:workflow-approval head=… by=… -->` audit
comment per head, and the PR goes through every other gate below like any
Expand Down
15 changes: 11 additions & 4 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ referenced it) a lone `stage/050-review-pending`
| `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 immediately re-homes to an App-authored superseder (`signoff-rehome`), preserving commits and sign-offs while changing squash attribution; loss of push access re-homes immediately, and idle rebase work re-homes after the dwell). 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 10 minutes; a failed read is not cached and defers: no adoption, and an existing adoption is neither released nor re-homed until the read succeeds), and an adoption of such an author is released on the next pass, closing a still-open hive superseder with a note first. A fork PR is never superseded or re-homed into the base repository (that would run unreviewed fork code with the repository's trusted CI); it parks at `085` as `adoption-stalled:fork-rehome-refused` instead. | 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/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. A `workflow-path` fence the owner's approval releases ([#14664](https://github.com/hivecommons/hive/issues/14664)) is not such a rule: the comment reads "Needs a decision, not a merge" and asks for a trusted merger's GitHub **Approve** review (or a dashboard `/hive decision approve`) on the current head — a `/hive approve` reply does not release the fence — and still lists the sentinel alert and hold labels a person must clear (projectbluefin/testsuite#1037) | 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 |
| `stage/095-pre-merge-soak` | PR | lane admitted; the pre-merge soak window (`automerge.contributor_lane.soak_minutes`, default 30) is running before the merge is attempted. The dashboard shows it as **Soaking** on the merge-gate column with the time left; a quiet 095 past its dwell is a lane bug (the soak elapsed but the lane never promoted), so the stall note says so. 100 → 095 on a re-evaluation is a reclassification, not a regression | 45m (30m soak + 15m grace) |
| `stage/100-merge-queue` | PR | lane admitted and soak complete: merge-eligible, waiting for tide / the merge window — and every check on the head is green (tide excluded). A red optional check is 070/071/072 like any red CI | 3h |
Expand Down Expand Up @@ -679,7 +679,13 @@ nothing to fix, so the PR parks at `085` under `hive-signoff-attribution`
for a maintainer, with one `<!-- hive:maintainer-signoff-attribution
head=… -->` note per head naming what clears it (approve the head, merge
with a merge commit, or lift `auto_merge.squash_only`) and no contributor
nudge (projectbluefin/testsuite#991). Only a head made solely of App-signed
nudge (projectbluefin/testsuite#991). When the lane never merges the head
unattended, approved or not — tests removed, a human-merge path, or a
`workflow-path` fence the owner's approval cannot release (toggle off, or
the App lacks `workflows: write`) — the note, and the adoption-stalled note
that carries the same ask, offer only the by-hand merge with a merge commit
and name the rule; an open sentinel alert is named as a label a maintainer
must clear first (projectbluefin/testsuite#1037). Only a head made solely of App-signed
commits the hive never pushed — a person's own commit made with the App's
identity — goes back to its author by kind under
`hive-signoff-attribution`: `071` for a human, `072` for a clanker — never
Expand Down Expand Up @@ -976,8 +982,9 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
`stage/085-needs-decision` with "a maintainer must review and merge
this PR manually" — the lane does not merge it unattended, and the 085
note says the hive adopted it to repair CI and why it still will not
merge it (for `workflow-path`, a trusted merger's approval on the
current head releases the fence, [#14664](https://github.com/hivecommons/hive/issues/14664)).
merge it (for `workflow-path` with the owner-approval release on, the
085 note instead asks for a trusted merger's approval on the current
head, which releases the fence, [#14664](https://github.com/hivecommons/hive/issues/14664)).
- **supersede** (and the `dco-rehome`, `signoff-rehome` and
`in-place-stalled` second takeovers): the App PR's body opens with
`<!-- hive:carried-fence reason=<contributor-lane:…> from=#<n> -->`
Expand Down
54 changes: 54 additions & 0 deletions src/pkg/github/automerge/automerge_adoption_escape_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -582,3 +582,57 @@ func TestFormatSat(t *testing.T) {
}
}
}

// projectbluefin/testsuite#1037's shape: adopted in place, the hive's
// App-signed commit beside the contributor's, a requires_human verdict that
// blocks the re-home, a CI workflow edit and a sentinel alert. The stall
// note asked for an Approve review while the 085 entry comment said no
// approval overrides the manual-merge rule. Under an absolute rule both now
// say a person merges by hand; with the owner-approval release on, both ask
// for the approval (hivecommons/hive#14664).
func TestAdoptedSignoffStallAskAgreesWithWorkflowFence(t *testing.T) {
for name, release := range map[string]bool{"release off": false, "release on": true} {
t.Run(name, func(t *testing.T) {
p := adoptPolicy()
p.AdoptInPlace = true
p.DCORequired = func(string) (bool, bool) { return true, true }
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "comment"}, p)
defer done()
if release {
releaseWorkflowFence(h.e)
}
h.api.commitDetails = map[int][]stageCommitFixture{7: {
{message: "ci: run e2e on the new runner\n\nSigned-off-by: Mallory <mallory@example.com>", authorLogin: "mallory", authorName: "Mallory", authorEmail: "mallory@example.com"},
{message: "ci: pin the runner image\n\nSigned-off-by: hive[bot] <12345+hive[bot]@users.noreply.github.com>", authorLogin: testHiveAppBotLogin, authorName: "hive[bot]", authorEmail: "12345+hive[bot]@users.noreply.github.com"},
}}
h.adopt.prFiles = []map[string]any{{"filename": ".github/workflows/e2e.yml", "status": "modified", "additions": 3, "deletions": 1}}
adoptInPlaceAt(h, "f72fa44", contributorLaneReasonNoVerdict)
h.adopt.setCommitAuthor("f72fa44", testHiveAppBotLogin)
h.clock.advance(time.Minute)
h.e.noteStageVerdict("acme", "widget", 7, requiresHumanVerdict)
h.observe(adoptPR(7, "f72fa44", append([]string{"sentinel-alert"}, adoptedLabels...)...), contributorLaneReasonNoVerdict)

notes := stalledComments(h.api)
if len(notes) != 1 {
t.Fatalf("stall note: %q", h.api.comments)
}
if !strings.Contains(notes[0], "A sentinel alert is open on this PR: resolve it and have a maintainer clear its label first.") {
t.Fatalf("stall note does not name the sentinel alert:\n%s", notes[0])
}
hand := strings.Contains(notes[0], "The hive will not merge this head itself, approved or not: the PR edits CI workflow / action files")
approve := strings.Contains(notes[0], "approve the current head with a GitHub **Approve** review")
if hand == release || approve != release {
t.Fatalf("stall note (release=%v) hand=%v approve=%v:\n%s", release, hand, approve, notes[0])
}
var entry string
for _, c := range h.api.comments {
if strings.HasPrefix(c, stagelabels.DecisionCommentMarker) {
entry = c
}
}
if manual := strings.Contains(entry, "a maintainer must review and merge this PR manually"); entry == "" || manual == release || strings.Contains(entry, "releases the CI workflow-file fence") != release {
t.Fatalf("085 entry comment disagrees with the stall note (release=%v):\n%s", release, entry)
}
})
}
}
Loading
Loading