diff --git a/changelog.d/fixed-fork-guard-nudge.md b/changelog.d/fixed-fork-guard-nudge.md new file mode 100644 index 0000000000..5ab1a5926e --- /dev/null +++ b/changelog.d/fixed-fork-guard-nudge.md @@ -0,0 +1 @@ +- A fork pull request red only on a fork-guard check (such as a required `Canary` that cannot run on forks) is no longer nudged ("Failing checks: Canary") or adopted on each new head before it is parked: the guard's checks are remembered on the PR, a later head red on nothing else goes straight to `stage/085-needs-decision`, the nudge never lists a fork-guard check, and automatic adoption refuses a head whose only blocker is the guard (projectbluefin/utah-packages#862, #869). diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index d722629aa0..e1e68eba6f 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -370,7 +370,7 @@ used to admit the PR: | `head-changed-since-eval`, `merge-failed`, `merge-queue-required` (the base branch's ruleset only accepts merges through GitHub's merge queue and the transport is a static token that cannot enqueue, so the direct REST merge is refused; with App auth on a repo opted in through `auto_merge.native_merge_queue` these bases are enqueued instead, see [native-merge-queue.md](../native-merge-queue.md); logged as a skip rather than a merge error, [#14018](https://github.com/hivecommons/hive/issues/14018); the self-authored sweep then skips the direct merge on that base for 30 minutes and logs the skip once per PR head, [#14068](https://github.com/hivecommons/hive/issues/14068); the trusted-author, queued and contributor-lane sweeps skip it the same way), `required-checks-expected`, `behind`, `updated-branch`, `behind-update-budget-exhausted` (a behind self-authored PR the sweep did not update only because this tick's branch-update budget was spent; retried next tick, waits on the hive, [#12607](https://github.com/hivecommons/hive/issues/12607)), `release-hold*`, `native-merge-queued: queued (position N, STATE)` (the PR was enqueued into GitHub's native merge queue) and the failures `native-merge-queue-read`, `native-merge-queue-enqueue`, `native-merge-queue-method` — and no red check on the head | `100-merge-queue` | | CI red (required or optional check) while the PR is deferred to an open `[shared-ci]` incident (``, the governor's `deferred_incident`) for the same head | `050-review-pending` / `060-reviewed`, reason `shared-ci-incident:`: the base or a shared check is what is red, so the PR is never sent to 070/071/072, never nudged and never stalled; once the incident closes a still-red head is handed back as usual. Conflicts and requested changes stay author-facing ([#12606](https://github.com/hivecommons/hive/issues/12606)) | | CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip — the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:,` ("waiting for the base branch's CI to recover (…) — not this PR's fault"): never 070/071/072, never nudged, never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) | -| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or approve the run as the repository requires). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273)) | +| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or approve the run as the repository requires). The guard's checks are remembered on the PR's stage record: a head the CI-enriched enumeration has not classified yet (a new push, or a snapshot that dropped the PR) parks the same way when every red check in its check digest is one the guard refused before, so a fork PR is not nudged and adopted on each new head first ([projectbluefin/utah-packages#869](https://github.com/projectbluefin/utah-packages/pull/869)). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273)) | | any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees ✗). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` → 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) | | `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` | 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 | | `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` | diff --git a/src/pkg/github/automerge/automerge_contributor_adopt.go b/src/pkg/github/automerge/automerge_contributor_adopt.go index 4840918aa2..0e8a330444 100644 --- a/src/pkg/github/automerge/automerge_contributor_adopt.go +++ b/src/pkg/github/automerge/automerge_contributor_adopt.go @@ -663,6 +663,15 @@ func (c *Engine) adoptContributorPR(ctx context.Context, store *stagelabels.Stor if !due { return 0, nil } + if !requested && !forced && adoptionForkGuardOnly(obs) { + // The guard asks a maintainer to publish the branch; an in-place + // push cannot turn it green and an automatic copy would publish it + // without that maintainer (projectbluefin/utah-packages#862). The + // PR stays parked at 085; nothing is recorded, so a maintainer's + // adopt-supersede request still goes through. + c.debug("stage labels: adoption due but only a fork guard is red; left for a maintainer", "repo", obs.Display, "pr", obs.Number, "head", obs.HeadSHA, "checks", obs.ForkGuardChecks) + return 0, nil + } if l := adoptionBlocked(obs.Labels); l != "" { c.info("stage labels: adoption due but blocked by label", "repo", obs.Display, "pr", obs.Number, "label", l) return 0, nil @@ -1936,6 +1945,18 @@ func adoptionOptionalCheckOnly(obs stageObservation) bool { return strings.HasPrefix(nonEmpty(obs.Reason, obs.LaneReason), stageReasonOptionalCheckFailing) && !verdictBlocks(obs.Detail) && !verdictNeedsHuman(obs.Detail) } +// adoptionForkGuardOnly reports a head whose only blocker is a fork guard: +// every red check refuses the PR only because it is from a fork +// (ForkGuardChecks, hivecommons/hive#14273) and the stage reason is that +// guard or the red CI it explains. A review or DCO ask is still adoptable. +func adoptionForkGuardOnly(obs stageObservation) bool { + if len(obs.ForkGuardChecks) == 0 { + return false + } + r := nonEmpty(obs.Reason, obs.LaneReason) + return strings.HasPrefix(r, stageReasonForkGuard) || strings.HasPrefix(r, stageReasonOptionalCheckFailing) || classifyCIReason(r) == ciReasonRed +} + // adoptionStale reports whether the adopted head has sat unchanged for the // 074 dwell with CI not running. A record whose head clock was never // stamped (pre-hivecommons/hive#13040) is not stale: AdoptedAt may predate diff --git a/src/pkg/github/automerge/automerge_contributor_nudge.go b/src/pkg/github/automerge/automerge_contributor_nudge.go index 83a833e5d5..a4e132fbd6 100644 --- a/src/pkg/github/automerge/automerge_contributor_nudge.go +++ b/src/pkg/github/automerge/automerge_contributor_nudge.go @@ -3,6 +3,7 @@ package automerge import ( "context" "fmt" + "slices" "strings" "time" @@ -283,6 +284,17 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, return 0, nil } checks, asks, human := nudgeDiagnosisRouted(obs.Reason, obs.Detail, obs.Route) + // A fork guard is a maintainer's to clear (hivecommons/hive#14273): the + // author is never asked to fix it, and a head red on nothing else is not + // nudged at all — no nudge, no adoption grace + // (projectbluefin/utah-packages#869). + if kept := withoutForkGuard(checks, obs.ForkGuardChecks); len(kept) < len(checks) { + checks = kept + if len(checks) == 0 && len(asks) == 0 { + c.debug("stage labels: contributor nudge skipped, only a fork guard is red", "repo", obs.Display, "pr", obs.Number, "head", obs.HeadSHA, "checks", obs.ForkGuardChecks) + return 0, nil + } + } n := ContributorNudge{ Owner: obs.Owner, Repo: obs.Repo, Display: obs.Display, Number: obs.Number, HeadSHA: obs.HeadSHA, Title: obs.Title, URL: obs.URL, Author: obs.Author, OpenedAt: obs.OpenedAt, @@ -306,6 +318,21 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, return 1, nil } +// withoutForkGuard drops the fork-guard checks from a nudge's failing +// checks; checks is returned unchanged when there is no guard. +func withoutForkGuard(checks, guard []string) []string { + if len(guard) == 0 { + return checks + } + var out []string + for _, name := range checks { + if !slices.Contains(guard, strings.TrimSpace(name)) { + out = append(out, name) + } + } + return out +} + // resolveNudge tells the sink a PR that was in stage 072 last cycle has // left it (new head went green, closed, merged, adopted). func (c *Engine) resolveNudge(ctx context.Context, rec stagelabels.Record, had bool, obs stageObservation) { diff --git a/src/pkg/github/automerge/automerge_fork_guard_test.go b/src/pkg/github/automerge/automerge_fork_guard_test.go new file mode 100644 index 0000000000..100bf6ec2a --- /dev/null +++ b/src/pkg/github/automerge/automerge_fork_guard_test.go @@ -0,0 +1,121 @@ +package automerge + +import ( + "context" + "reflect" + "slices" + "strings" + "testing" + "time" + + hgithub "github.com/hivecommons/hive/pkg/github" +) + +// projectbluefin/utah-packages#862 / #869: the fork-guard park only knew the +// head the last CI-enriched enumeration saw, so every new head of a fork PR +// red only on its `Canary` fork guard was handed back to its author first — +// a "fix Canary" nudge and, after the grace, an adoption — before the next +// enumeration parked it at 085 again. A head red on the guard alone now goes +// straight to the park; a head with any other red check keeps the +// author-facing route unchanged. +func TestForkGuardHeadNeitherNudgedNorAdopted(t *testing.T) { + cases := []struct { + name string + // red is the check digest of the second head, which the + // enumeration has not classified yet. + red []string + wantNudge bool + }{ + {name: "fork guard only", red: []string{"Canary"}}, + {name: "fork guard and a real failure", red: []string{"Canary", "unit"}, wantNudge: true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var guard []string + p := adoptPolicy() + p.ForkGuard = func(string, int, string) []string { return guard } + h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "comment"}, p) + defer done() + h.e.checkSummary = func(_ context.Context, _, _, sha string) (hgithub.CommitChecksSummary, error) { + if sha == "aaa" { + return hgithub.CommitChecksSummary{Total: 3, Green: 2, Red: []string{"Canary"}, DCO: 1}, nil + } + return hgithub.CommitChecksSummary{Total: 3, Green: 3 - len(tc.red), Red: tc.red, DCO: 1}, nil + } + key := stageKey("acme", "widget", 7) + + // The enumeration classified head aaa: parked, never nudged. + guard = []string{"Canary"} + h.observe(adoptPR(7, "aaa"), "required-check-failing:Canary") + parked := []string{"stage/085-needs-decision", "role/contributor", "author/clanker"} + h.observe(adoptPR(7, "aaa", parked...), "required-check-failing:Canary") + if got := nudgeComments(h.api); len(got) != 0 || len(h.sink.nudges) != 0 { + t.Fatalf("fork-guard head nudged: %v", got) + } + if rec, _ := h.e.stageStoreOrShared().Get(key); !slices.Equal(rec.ForkGuardChecks, []string{"Canary"}) { + t.Fatalf("fork guard not remembered: %+v", rec.ForkGuardChecks) + } + + // A new head the enumeration has not seen: the policy knows nothing. + guard = nil + h.api.reset() + h.observe(adoptPR(7, "bbb", parked...), "required-check-failing:Canary") + nudges := nudgeComments(h.api) + if !tc.wantNudge { + if len(nudges) != 0 || len(h.sink.nudges) != 0 { + t.Fatalf("new fork-guard head nudged: %v", nudges) + } + } else if len(nudges) != 1 || !strings.Contains(nudges[0], "head=bbb n=1") || !strings.Contains(nudges[0], "`Canary`") { + t.Fatalf("new head with a real failure not nudged: %v", h.api.comments) + } + + // Past every grace: adopted only when a real failure is red. + returned := []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"} + labels := parked + if tc.wantNudge { + labels = returned + } + h.api.reset() + h.clock.advance(3 * time.Hour) + h.observe(adoptPR(7, "bbb", labels...), "required-check-failing:Canary") + adopted := len(h.adopt.pulls) > 0 || len(adoptionComments(h.api)) > 0 + if adopted != tc.wantNudge { + t.Fatalf("adopted = %v, want %v: pulls=%d comments=%v", adopted, tc.wantNudge, len(h.adopt.pulls), h.api.comments) + } + }) + } +} + +// A nudge never lists a fork-guard check; adoption refuses a head whose +// only blocker is the guard but not one with a review or DCO ask. +func TestForkGuardNudgeChecksAndAdoptionPredicate(t *testing.T) { + guard := []string{"Canary"} + if got := withoutForkGuard([]string{"Canary"}, guard); len(got) != 0 { + t.Fatalf("guard-only checks = %v", got) + } + if got := withoutForkGuard([]string{"Canary", "unit"}, guard); !reflect.DeepEqual(got, []string{"unit"}) { + t.Fatalf("guard plus real failure = %v", got) + } + if got := withoutForkGuard([]string{"Canary"}, nil); !reflect.DeepEqual(got, []string{"Canary"}) { + t.Fatalf("no guard evidence = %v", got) + } + + cases := []struct { + name string + obs stageObservation + want bool + }{ + {name: "parked on the guard", obs: stageObservation{Reason: stageReasonForkGuard + "Canary", ForkGuardChecks: guard}, want: true}, + {name: "guard is the red required check", obs: stageObservation{Reason: "required-check-failing:Canary", ForkGuardChecks: guard}, want: true}, + {name: "guard is the red optional check", obs: stageObservation{Reason: stageReasonOptionalCheckFailing + "Canary", ForkGuardChecks: guard}, want: true}, + {name: "review ask beside the guard", obs: stageObservation{Reason: "reviewer-verdict:changes_requested", LaneReason: "required-check-failing:Canary", ForkGuardChecks: guard}}, + {name: "real failure, no guard evidence", obs: stageObservation{Reason: "required-check-failing:Canary"}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := adoptionForkGuardOnly(tc.obs); got != tc.want { + t.Fatalf("adoptionForkGuardOnly = %v, want %v", got, tc.want) + } + }) + } +} diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index bfd2b11315..d7d232b26a 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -898,6 +898,7 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) result.Items++ c.foldHumanReturnLabel(ctx, store, list) c.foldRecordedDecision(ctx, list) + c.foldForkGuard(ctx, tracker, store, list, now) verdict, role, obs := resolveStage(list) key := stageKey(obs.Owner, obs.Repo, obs.Number) if verdict.Rank == stageRankNone { diff --git a/src/pkg/github/automerge/automerge_stage_sharedci.go b/src/pkg/github/automerge/automerge_stage_sharedci.go index bfb72d467b..5f3afa2733 100644 --- a/src/pkg/github/automerge/automerge_stage_sharedci.go +++ b/src/pkg/github/automerge/automerge_stage_sharedci.go @@ -1,10 +1,14 @@ package automerge import ( + "context" + "slices" "strings" + "time" "github.com/hivecommons/hive/pkg/stageengine" "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" ) // stageReasonSharedCIIncident prefixes the recorded reason when a red PR is @@ -63,6 +67,65 @@ func stageForkGuard(policy StageLabelPolicy, owner, repo string, number int, hea return policy.ForkGuard(owner+"/"+repo, number, head) } +// foldForkGuard keeps a fork PR's fork-guard evidence across heads and +// sweeps. The policy answers only for the head the last CI-enriched +// enumeration saw, so every new head (and every snapshot that dropped the +// PR) read as plain red CI: 072, a nudge telling the author to fix the +// guard, and after the grace an adoption — before the next enumeration +// parked the PR at 085 again (projectbluefin/utah-packages#862, #869). +// +// Fresh evidence is remembered on the record. Without it, a fork head whose +// every red check — from the head's own check digest, not the lane's +// reason, which names one check — is one the PR's guard refused before is +// read as the same guard, so it goes straight to the 085 park. A head with +// any other red check keeps the author-facing route. +func (c *Engine) foldForkGuard(ctx context.Context, tracker *StageTracker, store *stagelabels.Store, list []stageObservation, now time.Time) { + var o *stageObservation + for i := range list { + if len(list[i].ForkGuardChecks) > 0 { + store.NoteForkGuard(stageKey(list[i].Owner, list[i].Repo, list[i].Number), list[i].ForkGuardChecks) + return + } + if o == nil && strings.TrimSpace(list[i].HeadSHA) != "" { + o = &list[i] + } + } + if o == nil || o.Merged || o.HeadRepo == "" || headInBaseRepo(*o) { + return + } + key := stageKey(o.Owner, o.Repo, o.Number) + rec, ok := store.Get(key) + if !ok || len(rec.ForkGuardChecks) == 0 { + return + } + head := o.HeadSHA + red := false + for _, l := range list { + if l.HeadSHA == head && (classifyCIReason(l.Reason) == ciReasonRed || l.Detail.RedCheck(head) != "") { + red = true + break + } + } + if !red { + return + } + summary, known := c.headChecks(ctx, tracker, key, *o, now) + if !known || len(summary.Red) == 0 { + return + } + for _, name := range summary.Red { + if !slices.Contains(rec.ForkGuardChecks, name) { + return + } + } + for i := range list { + if list[i].HeadSHA == head { + list[i].ForkGuardChecks = append([]string(nil), summary.Red...) + } + } + c.debug("stage labels: fork guard carried to a head the enumeration has not classified", "repo", o.Display, "pr", o.Number, "head", head, "checks", summary.Red) +} + func baseBranchRedReason(checks []string) string { return stageengine.BaseBranchRedReason(checks) } // stageReasonWaitsOnHive reports reasons that leave the PR waiting on the diff --git a/src/pkg/stagelabels/store.go b/src/pkg/stagelabels/store.go index 48b5a97f1f..5ec74dd4a0 100644 --- a/src/pkg/stagelabels/store.go +++ b/src/pkg/stagelabels/store.go @@ -145,6 +145,14 @@ type Record struct { // head: a mention is an email, and the same cause on a new head is the // same ask. MentionCause string `json:"mention_cause,omitempty"` + // ForkGuardChecks are the checks last seen refusing this PR only + // because it is from a fork (hgithub.PullRequest.ForkGuardChecks, + // hivecommons/hive#14273). They outlive the head: the policy answers + // only for the head the last CI-enriched enumeration saw, and a fork + // guard refuses every head of the PR, so the stage pass reads a later + // head red on nothing else as the same guard instead of handing it back + // to its author (projectbluefin/utah-packages#862, #869). + ForkGuardChecks []string `json:"fork_guard_checks,omitempty"` // DCOHead, DCOTotal and DCOUnsigned cache the commit check for one head // (hivecommons/hive#12542): how many non-merge commits the PR carried // and how many lacked a Signed-off-by trailer. DCOUnsignedHive / @@ -2221,6 +2229,20 @@ func (s *Store) NoteAdoptDiffFence(key, reason string) { s.dirty = true } +// NoteForkGuard records the checks fresh evidence showed refusing the PR +// only because it is from a fork, on an existing record. +func (s *Store) NoteForkGuard(key string, checks []string) { + s.mu.Lock() + defer s.mu.Unlock() + r, ok := s.items[key] + if !ok || len(checks) == 0 || slices.Equal(r.ForkGuardChecks, checks) { + return + } + r.ForkGuardChecks = append([]string(nil), checks...) + s.items[key] = r + s.dirty = true +} + // SetCoveringPR records (or, with an empty prKey, clears) the covering PR // of an issue the store knows. A no-op for an unknown key. func (s *Store) SetCoveringPR(key, prKey string) {