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-merge-guard-stage-flap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A PR parked at 085 on a red check no longer flips to 080 whenever a contributor-lane pass is refused the destination-merge lock. The lane reports that refusal (`base-refresh:merge-guard`, "destination merge already in progress") together with its error, and the classifier's errored-lane branch ran first: an approved head read as a weak 080, which replaced the standing 085 and seated the red PR at the front of a merge train until the next evaluated pass put it back (projectbluefin/utah-packages#917, about 15 round trips on one head). The refusal is now no stage opinion, error or not.
4 changes: 2 additions & 2 deletions src/docs/adr/0025-central-stage-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ hub read that store and nothing else (`stageStoreOrShared`,
(`src/pkg/github/automerge/automerge_stage_labels.go:365`), observations are
sorted by `stageLanePrecedence` (self 3 > trusted 2 > contributor 1,
`src/pkg/github/automerge/automerge_stage_labels.go:177`), each is classified
by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:261`)
by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:342`)
into a ranked opinion (`prstage.RankNone..prstage.RankOwned`,
`src/pkg/stageengine/prstage/types.go:145-148`), and
`ResolveStage` picks the winner
(`src/pkg/stageengine/derive_pr_classify.go:454`). These PR helpers now
(`src/pkg/stageengine/derive_pr_classify.go:718`). These PR helpers now
live in the engine (#13779); automerge keeps only gathering-side previews. Shared concepts β€”
parking (045/085, `needs-human`, hold labels), author kind (070/071/072),
adoption (074), terminal states, `origin/*` β€” are modelled twice with
Expand Down
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,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, `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)) |
| 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 even though the lane reports it as an error, so it never reads as 080 over a standing 085, [utah-packages#917](https://github.com/projectbluefin/utah-packages/pull/917)) | 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)) |

**Whose check run it is.** GitHub lists check runs per commit, and two PRs can share a head (a maintainer's in-repo copy of a fork PR). When a PR is evaluated, a red check run another PR produced on that head does not count against it. A run whose `pull_requests` names other PRs but not this one is dropped, and so is a run naming no PR (how GitHub reports a fork PR's runs) that ran for a different head: the Actions workflow run behind its check suite names the head repository and branch, so an in-repo copy pushed under the fork's branch name is still told apart; a suite from another app, with no workflow run, is judged on its head branch. projectbluefin/utah-packages#890 went to 072 for "Failing checks: Canary" on the fork PR #878's Canary run at the same SHA, before #890's own Canary had started. A lookup that fails keeps the run.

Expand Down
4 changes: 2 additions & 2 deletions src/docs/stage-engine-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ Scope: freeze today's behaviour. No production code changes.

- `src/pkg/stageengine/testdata/stage_goldens/*.json`: one fixture per
lane Γ— reason Γ— verdict Γ— author-kind Γ— adoption combination reachable in
`ClassifyStage`/`ResolveStage` (`src/pkg/stageengine/derive_pr_classify.go:261`,
`src/pkg/stageengine/derive_pr_classify.go:454`), serialised as
`ClassifyStage`/`ResolveStage` (`src/pkg/stageengine/derive_pr_classify.go:342`,
`src/pkg/stageengine/derive_pr_classify.go:718`), serialised as
`[]stageObservation` β†’ `{stage, rank, reason, role, terminal}`. Generated
by a `go test -run TestStageGoldens -update` flag; checked in.
- `src/pkg/github/testdata/issue_stage_goldens/*.json`: one per bucket Γ—
Expand Down
97 changes: 97 additions & 0 deletions src/pkg/github/automerge/automerge_stage_merge_guard_err_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
package automerge

import (
"context"
"testing"
"time"

gh "github.com/google/go-github/v72/github"
hgithub "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/stageengine/prstage"
"github.com/hivecommons/hive/pkg/stagelabels"
)

// projectbluefin/utah-packages#917, 2026-11-07 12:02–16:11Z: a fork PR with
// an approve verdict, parked at 085 on its fork-guarded red required Canary,
// went 085 β†’ 080 β†’ 085 about 15 times on one unchanged head. Each 080 came
// from a contributor-lane pass that could not take the destination-merge
// lock ("destination merge already in progress": another sweep was
// evaluating a PR into the same base). The lane returns that refusal as
// base-refresh:merge-guard WITH the error, so the observation is Err, and
// the classifier's lane-errored branch ran before the hand-off check:
// approve verdict + no CI reason = a weak 080, the merge train seated the
// PR as its front, and the next evaluated pass put it back at 085.
//
// The test replays that: evaluated passes and merge-guard passes (recorded
// exactly as the lane records them, error included) alternate, both inside
// and outside the 15-minute reversal guard and the 30-minute dampener
// window. The PR must stay at 085 with the fork-guard reason and 080 must
// never be written.
func TestMergeGuardRefusalKeepsForkGuardedPRAtNeedsDecision(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 7, 12, 0, 0, 0, time.UTC)}
const head = "7e52182c0"
policy := StageLabelPolicy{Enabled: true, ForkGuard: func(repo string, number int, h string) []string {
if h == head {
return []string{"Canary"}
}
return nil
}}
e := newNudgeEngine(t, apiURLOf(t, api), clock, &fakeNudgeSink{}, policy)
ctx := context.Background()
labels := []string{"role/trusted", "author/clanker"}
key := stageKey("acme", "widget", 917)
pass := func(n int, mergeGuard bool) {
t.Helper()
api.reset()
pr := nudgePR(917, head, labels...)
pr.Head.Repo = &gh.Repository{FullName: gh.Ptr("kylerankin/widget")}
e.recordStage(stageLaneSelf, "acme/widget", "acme", "widget", pr, "not-app-authored", false, nil)
if mergeGuard {
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, basePreparationPrefix+"merge-guard", false, hgithub.ErrDestinationMergeBusy)
} else {
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, "required-check-failing:Canary", false, nil)
e.noteStageRole("acme", "widget", 917, stagelabels.RoleTrusted)
}
e.noteStageVerdict("acme", "widget", 917, ContributorLaneVerdict{Configured: true, Approved: true, Verdict: "approve"})
if _, err := e.ApplyStageLabels(ctx); err != nil {
t.Fatal(err)
}
for _, batch := range api.added {
for _, l := range batch {
if l == stagelabels.AwaitingMergeAdmission.Label() {
t.Fatalf("pass %d (merge-guard=%v) wrote %s on an unchanged red fork-guarded head", n, mergeGuard, l)
}
}
}
labels = stageLabelsAfter(labels, api)
if got := stageLabelOf(labels); got != stagelabels.NeedsDecision.Label() {
t.Fatalf("pass %d (merge-guard=%v): stage %q, want %s", n, mergeGuard, got, stagelabels.NeedsDecision.Label())
}
if rec, _ := e.stageStoreOrShared().Get(key); rec.Stage != stagelabels.NeedsDecision || rec.Reason != prstage.StageReasonForkGuard+"Canary" {
t.Fatalf("pass %d (merge-guard=%v): record %s %q, want 085 %q", n, mergeGuard, rec.Stage, rec.Reason, prstage.StageReasonForkGuard+"Canary")
}
}
pass(0, false)
// Live gaps: the refusal, then the evaluated pass 2–3 minutes later,
// then the next round trip 30–60 minutes on.
gaps := []time.Duration{2 * time.Minute, 3 * time.Minute, 35 * time.Minute, 2 * time.Minute, 50 * time.Minute, 70 * time.Second, 70 * time.Second, 40 * time.Minute}
for i, gap := range gaps {
clock.advance(gap)
pass(i+1, i%2 == 0)
}
}

// The classifier view of the same refusal: a lane that could not take the
// destination-merge lock never looked at the PR, error or not, so it has
// no stage opinion even when every author-side gate looks satisfied.
func TestErroredMergeGuardIsNoStageOpinion(t *testing.T) {
o := stageObservation{Lane: stageLaneContributor, HeadSHA: "sha", Reason: prstage.StageReasonBaseRefreshMergeGuard, Err: true}
o.Detail.VerdictKnown = true
o.Detail.Verdict.Approved = true
o.Detail.Verdict.Verdict = "approve"
if v := classifyStage(o); v.Rank != stageRankNone {
t.Fatalf("errored merge-guard classified %+v, want no opinion", v)
}
}
8 changes: 8 additions & 0 deletions src/pkg/stageengine/derive_pr_classify.go
Original file line number Diff line number Diff line change
Expand Up @@ -350,6 +350,14 @@ func ClassifyStage(o stageObservation) stageVerdict {
if reason != "closed" && reason != "gone" && reason != "label-removed" && HasLabelFold(o.Labels, prstage.SupersessionPendingLabel) && HasLabelFold(o.Labels, NeedsHumanLabel) && !HasLabelFold(o.Labels, "hive/keep-open") {
return stageVerdict{Stage: stagelabels.NeedsDecision, Rank: stageRankOwned, Human: true, Reason: prstage.ReasonSupersessionPending}
}
if reason == prstage.StageReasonBaseRefreshMergeGuard {
// The lane could not take the destination-merge lock, so it never
// looked at the PR. Lanes return that refusal with its error; read
// through the errored branch below, an approved head became a weak
// 080 that replaced a standing 085 on the same red head and seated
// it at a merge train's front (projectbluefin/utah-packages#917).
return stageVerdict{}
}
if o.Err {
// The lane tripped before deciding. If every author-side gate is
// already satisfied the PR is waiting on the hive, not the author.
Expand Down
Loading