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-stage-label-flap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- PR stage labels no longer flip between two stages on every pass with nothing changed. Two sweeps (the engine's ticker and the main loop's queued sweep) reconcile alternate passes from one tracker. A contributor lane that skipped a PR because another merge to its destination was in flight recorded `base-refresh:merge-guard`, which was written as an awaiting-admission stage over the stage the other sweep set a minute earlier (projectbluefin/utah-packages#869 080↔085, #873 080↔090); it is now no opinion. And a lower lane no longer overwrites the stage a higher lane set for the same head while that lane simply did not run this pass, for up to 30 minutes (projectbluefin/utah-packages#878 070↔072).
12 changes: 11 additions & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,7 +380,7 @@ used to admit the PR:
| `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `reporter-trust-hold`, `workflow-permission` (GitHub refused update-branch or the merge-forward with a 403 because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission; no token the hive holds can push that update, so it is not sent to 070), `fork-workflow-update` (the same update-branch refusal on a fork head: the App is not installed on the fork, so no grant lets it push there), `linked-issue:hold:#N:<label>` / `linked-issue:needs-decision:#N:<label>` (an open issue the PR closes is held or parked β€” see [Holding an issue](glossary-and-operations.md#holding-an-issue)) | human hand-off, **decision** cause β†’ routed by the head's evidence (below); lands at `085-needs-decision` when the head is otherwise clean. `contributor-lane:workflow-path` reads "awaiting owner approval": a trusted merger's `APPROVED` review on the current head (or a `/hive decision approve`, typed or from the dashboard, which also answers a `requires_human` verdict on that head) releases the fence and the lane merges the PR itself (`owner_approval_releases_workflow_fence`, [#14664](https://github.com/hivecommons/hive/issues/14664)); only with the toggle off, or when the App lacks `workflows: write` for the merge (`hive:unauthorized`, `merge-workflow-path`), does an approved head park at `090-ready-for-human-merge` for a person's click |
| `merge-refused:review-required` (GitHub answered the merge with 405 "At least N approving review(s) is/are required by reviewers with write access"), `merge-refused:method-not-allowed` (405 "Merge commits / Squash merges / Rebase merges are not allowed on this repository") | human hand-off, **decision** cause, as above: lands at `085-needs-decision` when the head is otherwise clean, and the entry comment names the rule GitHub refused the merge on. Every sweep (self-authored, trusted-author, queued, contributor lane) logs these as skips, not `merge-failed` errors, and stops calling merge: a review refusal is remembered per PR head and re-armed when the head moves, when GitHub's `mergeable_state` for the PR changes (an approving review turns `blocked` into `clean`), or after 30 minutes; a method refusal is remembered per repository and method for 30 minutes. The hive never switches the merge method on its own (a forward merge or a `merge-method/merge` PR must not be squashed), so `method-not-allowed` is a manual-merge park. When a person's change request still stands on the PR (their latest review is `CHANGES_REQUESTED`, on any head, and it was neither dismissed nor followed by their approval), the `review-required` comment does not ask for an approval over it. It names each reviewer, the commit they reviewed and a compare link to what the hive pushed since, and asks them to re-review, or a maintainer to dismiss the review. GitHub keeps such a review standing across pushes ([projectbluefin/utah-packages#633](https://github.com/projectbluefin/utah-packages/pull/633)). A 405 "Pull Request has merge conflicts" is reported as `conflicting` (070), not `merge-failed`, and the self-authored sweep re-reads `mergeable_state` right before the merge call and skips a head GitHub now calls `dirty`, so it does not call merge on a conflicting PR. Any other 405, 409 or 422 is still `merge-failed` |
| `contributor-lane:no-claim` / `claim-*` / `author-association` / `no-linked-issue`, `untrusted-author-role`, `author-permission-missing` | human hand-off, **trust** cause β†’ routed by the head's evidence (below); lands at `090-ready-for-human-merge` when the head is otherwise clean |
| hand-offs (`not-app-authored`, `trusted-bot-lane`, `trusted-author:app-authored`, `contributor-lane:app-authored`), transient fetch errors | no opinion β€” the owning lane decides; nothing is written. An App-authored PR is handed off by the trusted-author and contributor-lane tiers under their own reason; the self-authored lane owns it, and its `review-gate:no-review-bundle` is the stage's reason while the swarm has not reviewed the head ([#14482](https://github.com/hivecommons/hive/issues/14482)) |
| hand-offs (`not-app-authored`, `trusted-bot-lane`, `trusted-author:app-authored`, `contributor-lane:app-authored`), transient fetch errors, `base-refresh:merge-guard` (the lane skipped the PR because a merge to its destination was in flight) | no opinion β€” the owning lane decides; nothing is written. An App-authored PR is handed off by the trusted-author and contributor-lane tiers under their own reason; the self-authored lane owns it, and its `review-gate:no-review-bundle` is the stage's reason while the swarm has not reviewed the head ([#14482](https://github.com/hivecommons/hive/issues/14482)) |

When several lanes see the same PR the self-authored lane outranks the
trusted-author lane, which outranks the contributor lane; the trusted-author
Expand All @@ -394,6 +394,16 @@ observation and the next hold only the contributor lane's `no-claim`; an
incomplete pass is treated as no opinion rather than written as 090 and
flipped back a minute later.

The same holds for an owned opinion. The tracker remembers which lane set a
PR's stage and for which head. When that lane outranks the lane deciding now,
did not report this pass, and last reported on the same head within 30
minutes, the lower lane's different stage is not written: the self-authored
lane runs only in the engine's ticker, so a trusted-bot fork PR it put at
`070-fixing` otherwise went to `072-returned-to-contributor` on every queued
sweep and back on the next tick (projectbluefin/utah-packages#878). A new
head, a closed or merged PR, or the owning lane staying away past 30 minutes
lets the other lane's stage through.

A maintainer's own PR is therefore not a 090 case at all: with
`auto_merge.trusted_authors` on (the hive's default spoke config β€”
`require_role: merger`, `require_github_permission: true`), the
Expand Down
196 changes: 196 additions & 0 deletions src/pkg/github/automerge/automerge_stage_flap_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
package automerge

import (
"context"
"strings"
"testing"
"time"

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

// projectbluefin/utah-packages, 11-05 21:10–21:29Z: once stage labels were
// written on contributor PRs, three fork PRs flipped stage on every pass with
// the head, checks and labels unchanged. Two sweeps feed the one stage
// tracker and each reconciles what its own pass saw:
//
// - the engine's tick pass (self-authored + trusted + contributor lanes) and
// the queued sweep (queued + trusted + contributor, no self-authored lane);
// - when one sweep held the destination-merge lock, the other's contributor
// lane recorded base-refresh:merge-guard ("not evaluated this pass"),
// which read as an owned 080 (#869 080↔085, #873 080↔090);
// - #878's self-authored lane (trusted-bot author) ran only in the tick
// pass, so its 070 alternated with the contributor lane's 072.

// stageLabelsAfter applies one pass's label writes to labels.
func stageLabelsAfter(labels []string, api *stageAPI) []string {
api.mu.Lock()
defer api.mu.Unlock()
removed := map[string]bool{}
for _, l := range api.removed {
removed[strings.ToLower(l)] = true
}
out := make([]string, 0, len(labels))
for _, l := range labels {
if !removed[strings.ToLower(l)] {
out = append(out, l)
}
}
for _, batch := range api.added {
for _, l := range batch {
if !hasLabelFold(out, l) {
out = append(out, l)
}
}
}
return out
}

func stageLabelOf(labels []string) string {
for _, l := range labels {
if strings.HasPrefix(l, "stage/") {
return l
}
}
return ""
}

func TestMergeGuardIsNoStageOpinion(t *testing.T) {
if got := basePreparationPrefix + "merge-guard"; got != prstage.StageReasonBaseRefreshMergeGuard {
t.Fatalf("lanes emit %q, the classifier knows %q", got, prstage.StageReasonBaseRefreshMergeGuard)
}
if v := classifyStage(stageObservation{Lane: stageLaneContributor, HeadSHA: "sha", Reason: prstage.StageReasonBaseRefreshMergeGuard}); v.Rank != stageRankNone {
t.Fatalf("merge-guard classified %+v, want no opinion", v)
}
// Base preparation proper still owns its stage.
if v := classifyStage(stageObservation{Lane: stageLaneContributor, HeadSHA: "sha", Reason: basePreparationReady}); v.Rank != stageRankOwned {
t.Fatalf("base-refresh:preparing classified %+v, want an owned stage", v)
}
}

// #869/#873: a merge-guard pass between two evaluated passes writes nothing.
func TestMergeGuardPassKeepsTheStage(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 5, 21, 10, 0, 0, time.UTC)}
e := newNudgeEngine(t, apiURLOf(t, api), clock, &fakeNudgeSink{}, StageLabelPolicy{Enabled: true})
labels := []string{"role/contributor", "author/clanker"}
pass := func(reason string) {
t.Helper()
api.reset()
e.recordStage(stageLaneSelf, "acme/widget", "acme", "widget", nudgePR(7, "aaa", labels...), "not-app-authored", false, nil)
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", nudgePR(7, "aaa", labels...), reason, false, nil)
e.noteStageRole("acme", "widget", 7, stagelabels.RoleContributor)
if _, err := e.ApplyStageLabels(context.Background()); err != nil {
t.Fatal(err)
}
labels = stageLabelsAfter(labels, api)
clock.at = clock.at.Add(70 * time.Second)
}
pass("required-check-failing:Canary")
settled := stageLabelOf(labels)
if settled == "" {
t.Fatalf("first pass wrote no stage: %v", labels)
}
for i := 0; i < 6; i++ {
reason := "required-check-failing:Canary"
if i%2 == 0 {
reason = prstage.StageReasonBaseRefreshMergeGuard
}
pass(reason)
if got := stageLabelOf(labels); got != settled || api.writes() != 0 {
t.Fatalf("pass %d (%s): stage %s β†’ %s, added=%v removed=%v", i+2, reason, settled, got, api.added, api.removed)
}
}
}

// #878: the lane that wrote the stage (self-authored, tick pass only) is
// absent from the queued sweep's pass; the contributor lane's different
// stage for the same head waits for it, within the grace. A new head, or the
// owning lane staying away past the grace, lets it through.
func TestAbsentOwningLaneKeepsTheStage(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 5, 21, 10, 0, 0, time.UTC)}
e := newNudgeEngine(t, apiURLOf(t, api), clock, &fakeNudgeSink{}, StageLabelPolicy{Enabled: true})
labels := []string{"role/trusted", "author/clanker"}
head := "95b9d22"
pass := func(tick bool) {
t.Helper()
api.reset()
pr := nudgePR(7, head, labels...)
if tick {
e.recordStage(stageLaneSelf, "acme/widget", "acme", "widget", pr, "check-failing:Canary", false, nil)
}
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, "required-check-failing:Canary", false, nil)
if _, err := e.ApplyStageLabels(context.Background()); err != nil {
t.Fatal(err)
}
labels = stageLabelsAfter(labels, api)
}
const owned, contributor = "stage/070-fixing", "stage/072-returned-to-contributor"
pass(true)
if got := stageLabelOf(labels); got != owned {
t.Fatalf("tick pass wrote %s, want %s", got, owned)
}
for i := 0; i < 8; i++ {
clock.at = clock.at.Add(65 * time.Second)
pass(i%2 == 1)
if got := stageLabelOf(labels); got != owned {
t.Fatalf("pass %d (tick=%v): %s β†’ %s with head and checks unchanged", i+1, i%2 == 1, owned, got)
}
}
// The owning lane stays away past the grace: the other lane's stage applies.
clock.at = clock.at.Add(stageOwnerAbsenceGrace + time.Minute)
pass(false)
if got := stageLabelOf(labels); got != contributor {
t.Fatalf("past the grace: %s, want %s", got, contributor)
}
// A new head is new input: no hold.
labels = []string{"role/trusted", "author/clanker", owned}
pass(true)
head = "08b9e69"
clock.at = clock.at.Add(time.Minute)
pass(false)
if got := stageLabelOf(labels); got != contributor {
t.Fatalf("new head: %s, want %s", got, contributor)
}
}

func TestStageOwnerHolds(t *testing.T) {
now := time.Date(2026, 11, 5, 21, 20, 0, 0, time.UTC)
owner := stageOwner{Lane: stageLaneSelf, Head: "aaa", Stage: stagelabels.Fixing, At: now.Add(-time.Minute)}
contrib := stageObservation{Lane: stageLaneContributor, HeadSHA: "aaa"}
only := []stageObservation{contrib}
want072 := stageVerdict{Stage: stagelabels.ReturnedToContributor, Rank: stageRankOwned}
for _, tc := range []struct {
name string
owner stageOwner
known bool
list []stageObservation
obs stageObservation
verdict stageVerdict
current stagelabels.Stage
had bool
want bool
}{
{name: "owning lane absent, same head", owner: owner, known: true, list: only, obs: contrib, verdict: want072, current: stagelabels.Fixing, had: true, want: true},
{name: "no owner recorded", owner: owner, known: false, list: only, obs: contrib, verdict: want072, current: stagelabels.Fixing, had: true},
{name: "no current stage", owner: owner, known: true, list: only, obs: contrib, verdict: want072, had: false},
{name: "terminal", owner: owner, known: true, list: only, obs: contrib, verdict: stageVerdict{Terminal: true, Rank: stageRankOwned}, current: stagelabels.Fixing, had: true},
{name: "new head", owner: owner, known: true, list: only, obs: stageObservation{Lane: stageLaneContributor, HeadSHA: "bbb"}, verdict: want072, current: stagelabels.Fixing, had: true},
{name: "another writer moved the stage", owner: owner, known: true, list: only, obs: contrib, verdict: want072, current: stagelabels.NeedsDecision, had: true},
{name: "same stage", owner: owner, known: true, list: only, obs: contrib, verdict: stageVerdict{Stage: stagelabels.Fixing, Rank: stageRankOwned}, current: stagelabels.Fixing, had: true},
{name: "owning lane reported", owner: owner, known: true, list: []stageObservation{{Lane: stageLaneSelf, HeadSHA: "aaa"}, contrib}, obs: contrib, verdict: want072, current: stagelabels.Fixing, had: true},
{name: "owner does not outrank", owner: stageOwner{Lane: stageLaneContributor, Head: "aaa", Stage: stagelabels.Fixing, At: owner.At}, known: true, list: []stageObservation{{Lane: stageLaneSelf, HeadSHA: "aaa"}}, obs: stageObservation{Lane: stageLaneSelf, HeadSHA: "aaa"}, verdict: want072, current: stagelabels.Fixing, had: true},
{name: "lanes without precedence never hold", owner: stageOwner{Lane: "queued", Head: "aaa", Stage: stagelabels.Fixing, At: owner.At}, known: true, list: []stageObservation{{Lane: "other", HeadSHA: "aaa"}}, obs: stageObservation{Lane: "other", HeadSHA: "aaa"}, verdict: want072, current: stagelabels.Fixing, had: true},
{name: "past the grace", owner: stageOwner{Lane: stageLaneSelf, Head: "aaa", Stage: stagelabels.Fixing, At: now.Add(-stageOwnerAbsenceGrace - time.Second)}, known: true, list: only, obs: contrib, verdict: want072, current: stagelabels.Fixing, had: true},
} {
t.Run(tc.name, func(t *testing.T) {
if got := stageOwnerHolds(tc.owner, tc.known, tc.list, tc.obs, tc.verdict, tc.current, tc.had, now); got != tc.want {
t.Fatalf("stageOwnerHolds = %v, want %v", got, tc.want)
}
})
}
}
Loading
Loading