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-mergeable-unknown-keeps-refusal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Stage labels: a pass where GitHub reports a PR's mergeable state as `unknown`, which it does while it recomputes the merge after the base moves, no longer changes the PR's stage. The contributor lane stops on `mergeable-unknown` before admission, review or CI, and an approved head read as "nothing left for the author" became a weak `stage/080-awaiting-merge-admission` for that pass: a PR waiting on a person's merge for `contributor-lane:no-linked-issue` went 090 → 080 → 090, an admitted PR at 095 or 100 dropped to 080, and a conflicting PR at 072 could take the trusted-author lane's 090 for a pass. `mergeable-unknown` is now no stage opinion, like the destination-merge guard (#16819), and another lane's weak opinion does not stand in for it; an owned opinion from another lane still applies. The pass also keeps the lane's merge-train verdict on the head instead of clearing it, so a person's merge stays out of the train. [projectbluefin/utah-packages#1222](https://github.com/projectbluefin/utah-packages/pull/1222) flipped 090 → 080 → 090 twice in one evening this way.
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 @@ -420,7 +420,7 @@ used to admit the PR:
| `label:needs-human`, `exempt-label`, `excluded-label:*`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `review-off` (a verdict is required but the review swarm is off, so none will be requested) / `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 dashboard `/hive decision approve`) 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. A head that also touches `auto_merge.human_merge_paths` (and that the pin-only exception cannot admit) is never asked for that approval, because the human-merge-path rule refuses the merge after it: no decision is owed, so it routes to `090-ready-for-human-merge` under the human-merge-path reason once it is reviewed, green and soaked, and so does a PR wearing the hive's own human-merge-path `hold` |
| `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. Any other 405, 409 or 422 is still `merge-failed` 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. |
| `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 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)) |
| 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)), `mergeable-unknown` (GitHub has not computed the merge yet, so the contributor lane stopped before admission, review or CI; no other lane's weak opinion, such as the trusted-author lane's `untrusted-author-role`, stands in for it either, so a 090, 072 or 095 never drops to 080 or 090 for the pass, [utah-packages#1222](https://github.com/projectbluefin/utah-packages/pull/1222)) | 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
2 changes: 1 addition & 1 deletion src/pkg/github/automerge/automerge_contributor_lane.go
Original file line number Diff line number Diff line change
Expand Up @@ -1889,7 +1889,7 @@ func contributorLaneConflictReason(pr *gh.PullRequest) string {
case "dirty", "conflicting":
return "conflicting"
case "unknown":
return "mergeable-unknown"
return prstage.StageReasonMergeableUnknown
default:
return ""
}
Expand Down
11 changes: 11 additions & 0 deletions src/pkg/github/automerge/automerge_contributor_lane_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -852,6 +852,17 @@ func TestTrySweepContributorLanePRSkipReasons(t *testing.T) {
{name: "behind updates branch", mutate: func(fx *contributorLaneFixture) { fx.mergeableState = "behind" }, wantReason: "check-pending", wantUpdate: 1},
{name: "conflicting", mutate: func(fx *contributorLaneFixture) { fx.mergeableState = "dirty" }, wantReason: "conflicting"},
{name: "unknown mergeability waits", mutate: func(fx *contributorLaneFixture) { fx.mergeableState = "unknown" }, wantReason: "mergeable-unknown"},
// The lane reads mergeability before admission: a real conflict
// outranks a standing refusal, and an unknown state stops the pass
// with no stage opinion (TestMergeableUnknownPassKeeps*).
{name: "unknown mergeability stops before admission", mutate: func(fx *contributorLaneFixture) {
fx.body = "No issue here."
fx.mergeableState = "unknown"
}, wantReason: prstage.StageReasonMergeableUnknown},
{name: "conflict outranks no linked issue", mutate: func(fx *contributorLaneFixture) {
fx.body = "No issue here."
fx.mergeableState = "dirty"
}, wantReason: "conflicting"},
{
name: "reviewer configured without approval",
verdict: func(string, int, string) ContributorLaneVerdict { return ContributorLaneVerdict{Configured: true} },
Expand Down
8 changes: 6 additions & 2 deletions src/pkg/github/automerge/automerge_merge_train.go
Original file line number Diff line number Diff line change
Expand Up @@ -1254,9 +1254,13 @@ func mergeTrainVerdictKey(lane, owner, repo string, number int) string {
// altogether, and its readiness tier. A verdict that says none of those
// (a handoff, an error) clears the mark. Keyed by lane so the
// trusted-author lane's "untrusted-author-role" for a PR the contributor
// lane admits never touches the contributor lane's train.
// lane admits never touches the contributor lane's train. A pass that
// stopped on GitHub's mergeable_state "unknown" evaluated nothing, so it
// keeps whatever verdict the lane last reached on the head: clearing it
// let a person's merge (contributor-lane:no-linked-issue) be seated in a
// train until the next evaluated pass (projectbluefin/utah-packages#1222).
func (c *Engine) noteMergeTrainOutcome(lane, owner, repo string, number int, sha, reason string) {
if c == nil || number <= 0 {
if c == nil || number <= 0 || reason == prstage.StageReasonMergeableUnknown {
return
}
key := mergeTrainVerdictKey(lane, owner, repo, number)
Expand Down
182 changes: 182 additions & 0 deletions src/pkg/github/automerge/automerge_stage_mergeable_unknown_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
package automerge

import (
"context"
"testing"
"time"

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

// GitHub reports mergeable_state "unknown" while it recomputes a merge (it
// does after the base moves). The contributor lane stops there, before
// admission, review or CI, and records prstage.StageReasonMergeableUnknown.
// Read as "approved, nothing left for the author" that pass was a weak 080:
// projectbluefin/utah-packages#1222 (no linked issue, approved, green, head
// unchanged all night) went 090 → 080 → 090 twice in one evening. The pass
// now has no stage opinion, so the stage the evaluated passes set stands.

// mergeableUnknownApproved is the reviewer verdict the tracker holds for the
// head on every pass, unknown ones included.
func mergeableUnknownApproved() ContributorLaneVerdict {
return ContributorLaneVerdict{Configured: true, Approved: true, Verdict: "approve"}
}

// (a) A person's merge (no linked issue) at 090 stays 090 across unknown
// passes, with nothing written.
func TestMergeableUnknownPassKeepsHumanMerge(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 19, 21, 0, 0, 0, time.UTC)}
verdict := mergeableUnknownApproved()
e, store := humanStageEngine(t, api.url, clock, &verdict, time.Hour)
const number = 1222
labels := []string{"role/contributor", "author/human"}
pass := func(reason string) {
t.Helper()
api.reset()
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", stagePR(number, labels...), reason, false, nil)
e.noteStageVerdict("acme", "widget", number, mergeableUnknownApproved())
if reason != prstage.StageReasonMergeableUnknown {
// The lane notes the tier only once it reaches admission.
e.noteStageRole("acme", "widget", number, stagelabels.RoleContributor)
}
if _, err := e.ApplyStageLabels(context.Background()); err != nil {
t.Fatal(err)
}
labels = stageLabelsAfter(labels, api)
}
pass(contributorLaneReasonNoLinkedIssue)
clock.at = clock.at.Add(time.Hour) // past the soak
pass(contributorLaneReasonNoLinkedIssue)
if got := stageOf(t, store, number); got != stagelabels.ReadyForHumanMerge {
t.Fatalf("settled stage = %v, want 090", got)
}
for i := 0; i < 6; i++ {
reason := contributorLaneReasonNoLinkedIssue
if i%2 == 0 {
reason = prstage.StageReasonMergeableUnknown
}
clock.at = clock.at.Add(70 * time.Second)
pass(reason)
if got := stageOf(t, store, number); got != stagelabels.ReadyForHumanMerge || api.writes() != 0 {
t.Fatalf("pass %d (%s): stage %v, added=%v removed=%v comments=%v", i+3, reason, got, api.added, api.removed, api.comments)
}
}
if got := stageLabelOf(labels); got != stagelabels.ReadyForHumanMerge.Label() {
t.Fatalf("label = %q, want %s", got, stagelabels.ReadyForHumanMerge.Label())
}
}

// (b) A conflicting PR the lane would also refuse (the trusted-author lane
// says untrusted-author-role) sits at 072. An unknown pass hides the
// conflict from the contributor lane; the trust lane's weak 090 candidate
// must not stand in for it.
func TestMergeableUnknownPassKeepsConflictReturn(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 19, 21, 0, 0, 0, time.UTC)}
e, _, store := newStageEngine(t, apiURLOf(t, api), clock)
const number = 1223
var labels []string
pass := func(reason string) {
t.Helper()
api.reset()
pr := nudgePR(number, "sha-conflict", labels...)
e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", pr, "untrusted-author-role", false, nil)
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, reason, false, nil)
e.noteStageVerdict("acme", "widget", number, mergeableUnknownApproved())
if reason != prstage.StageReasonMergeableUnknown {
e.noteStageRole("acme", "widget", number, 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("conflicting")
settled := stageLabelOf(labels)
if settled != stagelabels.ReturnedToContributor.Label() {
t.Fatalf("conflicting pass wrote %q (labels %v), want %s", settled, labels, stagelabels.ReturnedToContributor.Label())
}
for i := 0; i < 6; i++ {
reason := "conflicting"
if i%2 == 0 {
reason = prstage.StageReasonMergeableUnknown
}
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)
}
}
if rec, ok := store.Get(stageKey("acme", "widget", number)); !ok || rec.Stage != stagelabels.ReturnedToContributor || rec.Reason != "conflicting" {
t.Fatalf("record = %+v, want 072 conflicting", rec)
}
}

// (c) An admitted, approved PR at 095 keeps its stage across unknown passes
// instead of dropping to 080 for one.
func TestMergeableUnknownPassKeepsAdmittedStage(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 19, 21, 0, 0, 0, time.UTC)}
e, _, _ := newStageEngine(t, apiURLOf(t, api), clock)
const number = 1224
labels := []string{"role/trusted", "author/human"}
pass := func(reason string) {
t.Helper()
api.reset()
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", nudgePR(number, "sha-admitted", labels...), reason, false, nil)
e.noteStageVerdict("acme", "widget", number, mergeableUnknownApproved())
if reason != prstage.StageReasonMergeableUnknown {
e.noteStageRole("acme", "widget", number, stagelabels.RoleTrusted)
}
if _, err := e.ApplyStageLabels(context.Background()); err != nil {
t.Fatal(err)
}
labels = stageLabelsAfter(labels, api)
clock.at = clock.at.Add(70 * time.Second)
}
pass(contributorLaneReasonSoaking)
settled := stageLabelOf(labels)
if settled != stagelabels.PreMergeSoak.Label() {
t.Fatalf("soaking pass wrote %q (labels %v), want %s", settled, labels, stagelabels.PreMergeSoak.Label())
}
for i := 0; i < 6; i++ {
reason := contributorLaneReasonSoaking
if i%2 == 0 {
reason = prstage.StageReasonMergeableUnknown
}
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)
}
}
}

// An unknown pass evaluated nothing, so it keeps the lane's last
// merge-train verdict on the head: clearing #1222's no-linked-issue verdict
// let the train seat a person's merge until the next evaluated pass.
func TestMergeTrainUnknownOutcomeKeepsHumanMergeVerdict(t *testing.T) {
c := &Engine{}
c.noteMergeTrainOutcome(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf", prstage.ContributorLaneReasonNoLinkedIssue)
c.noteMergeTrainOutcome(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf", prstage.StageReasonMergeableUnknown)
if v, ok := c.mergeTrainVerdictFor(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf"); !ok || !v.humanMerge || v.reason != prstage.ContributorLaneReasonNoLinkedIssue {
t.Fatalf("verdict after an unknown pass = %+v, %v; want the no-linked-issue human merge kept", v, ok)
}
if !c.mergeTrainHeadBlocked(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf") {
t.Fatal("a person's merge must stay out of the train across an unknown pass")
}
// An unknown pass on a head the lane never judged records nothing.
c.noteMergeTrainOutcome(stageLaneContributor, "acme", "widget", 1225, "abc", prstage.StageReasonMergeableUnknown)
if v, ok := c.mergeTrainVerdictFor(stageLaneContributor, "acme", "widget", 1225, "abc"); ok {
t.Fatalf("unknown pass recorded %+v", v)
}
// An evaluated pass still replaces the verdict.
c.noteMergeTrainOutcome(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf", "")
if v, ok := c.mergeTrainVerdictFor(stageLaneContributor, "acme", "widget", 1222, "1bb4e6bf"); !ok || v.humanMerge || v.readiness != mergeTrainReadinessReady {
t.Fatalf("evaluated pass verdict = %+v, %v; want ready", v, ok)
}
}
Loading
Loading