From bc6ebcede2b0f92b9c5edde804b22e42d4189faa Mon Sep 17 00:00:00 2001 From: Danathar Date: Thu, 5 Nov 2026 17:04:55 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20fix(stage):=20a=20required=20che?= =?UTF-8?q?ck=20that=20never=20reported=20keeps=20the=20PR=20at=20060?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit projectbluefin/utah#1074 read "4/4 checks green … Ready for a human merge" while its ruleset-required checks never ran (opened with GITHUB_TOKEN). The check digest now names required contexts with nothing reported on the head (base branch required set, cached per repo and branch) and RouteHuman waits on them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar --- .../fixed-stage-required-checks-missing.md | 1 + .../stage-labels.md | 2 +- .../github/automerge/automerge_stage_human.go | 42 +++++++- .../automerge/automerge_stage_labels.go | 3 + .../automerge/automerge_stage_labels_test.go | 7 ++ .../automerge_stage_required_missing_test.go | 98 +++++++++++++++++++ src/pkg/github/commit_checks_required_test.go | 44 +++++++++ src/pkg/github/commit_checks_summary.go | 20 ++++ src/pkg/stagelabels/human.go | 12 +++ src/pkg/stagelabels/required_missing_test.go | 25 +++++ 10 files changed, 249 insertions(+), 5 deletions(-) create mode 100644 changelog.d/fixed-stage-required-checks-missing.md create mode 100644 src/pkg/github/automerge/automerge_stage_required_missing_test.go create mode 100644 src/pkg/github/commit_checks_required_test.go create mode 100644 src/pkg/stagelabels/required_missing_test.go diff --git a/changelog.d/fixed-stage-required-checks-missing.md b/changelog.d/fixed-stage-required-checks-missing.md new file mode 100644 index 0000000000..2acc48598d --- /dev/null +++ b/changelog.d/fixed-stage-required-checks-missing.md @@ -0,0 +1 @@ +- A contributor PR is no longer called "Ready for a human merge" while a required check has never reported on its head. projectbluefin/utah#1074, utah#1072 and utah-packages#873 read "N/N checks green … Ready for a human merge" because they were opened with `GITHUB_TOKEN`, so the ruleset-required checks never ran and GitHub would refuse the merge. The stage pass now reads the base branch's required checks (cached per repo and branch), names the ones with nothing reported ("required not reported: contract"), and keeps the PR at `060-reviewed` until they report. diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 7c70b15b32..1bba68b361 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -421,7 +421,7 @@ conflict reason and the contributor lane's soak — and | verdict changes_requested at the head, any red gating check, DCO sign-off missing, merge conflict (`conflicting` / `needs-rebase`) | `071-needs-author` (`author/human`) / `072-returned-to-contributor` (`author/clanker`); `070-fixing` when self-authored or `author/hive`. The 072 nudge lists every reason. Moving 085/090 → 071/072 is not a regression | | no verdict for this head yet, or nothing has reported on the head (just pushed) and the verdict is not already `requires_human` | `050-review-pending` — never 090 without a current-head approve | | verdict `requires_human` at the head (even on a fresh head nothing has reported on yet, [#13115](https://github.com/hivecommons/hive/issues/13115)), sentinel alert, hold-class label, no reviewer configured, or a non-trust human-only lane rule | `085-needs-decision` + one entry comment naming the decision ("Needs a decision, not a merge: a sentinel alert is open on this PR.") | -| checks still running / unreadable, or the lane's soak not yet elapsed | `060-reviewed` (not 095: that stage means the lane has *admitted* the head, which a trust-blocked PR never is) | +| checks still running / unreadable, a required check (branch protection or ruleset) with nothing reported on the head (a PR opened with `GITHUB_TOKEN` triggers no workflow; projectbluefin/utah#1074), or the lane's soak not yet elapsed | `060-reviewed` (not 095: that stage means the lane has *admitted* the head, which a trust-blocked PR never is) | | everything above clean and only trust in the way | `090-ready-for-human-merge` + one entry comment: "Ready for a human merge: verdict approved @abc1234, 55/55 checks green, DCO yes, soak 1h0m0s elapsed. Blocked only by `role/newcomer` (below require_tiers)." | The entry comments are posted once per stage visit (a flip 085 ↔ 090 is a diff --git a/src/pkg/github/automerge/automerge_stage_human.go b/src/pkg/github/automerge/automerge_stage_human.go index 9765f5ec64..5fda967274 100644 --- a/src/pkg/github/automerge/automerge_stage_human.go +++ b/src/pkg/github/automerge/automerge_stage_human.go @@ -44,11 +44,45 @@ type humanChecksEntry struct { // CheckSummarizer reads the check digest for a head; tests swap it. type CheckSummarizer func(ctx context.Context, owner, repo, sha string) (hgithub.CommitChecksSummary, error) -func (c *Engine) summarizeChecks(ctx context.Context, owner, repo, sha string) (hgithub.CommitChecksSummary, error) { +func (c *Engine) summarizeChecks(ctx context.Context, owner, repo, sha string, required func() map[string]bool) (hgithub.CommitChecksSummary, error) { if c.checkSummary != nil { return c.checkSummary(ctx, owner, repo, sha) } - return hgithub.SummarizeCommitChecks(ctx, c.gh, owner, repo, sha) + return hgithub.SummarizeCommitChecksRequired(ctx, c.gh, owner, repo, sha, required()) +} + +// humanRequiredEntry is one base branch's required check set. +type humanRequiredEntry struct { + at time.Time + set map[string]bool +} + +// headRequiredChecks is the required check set of obs's base branch (branch +// protection, rulesets, else the configured list), cached per repo and +// branch for humanChecksTTL; nil when unknown. +func (c *Engine) headRequiredChecks(ctx context.Context, tracker *StageTracker, obs stageObservation, now time.Time) map[string]bool { + base := strings.TrimSpace(obs.BaseRef) + if base == "" || c.gh == nil { + return nil + } + key := strings.ToLower(obs.Owner+"/"+obs.Repo) + "@" + base + tracker.mu.Lock() + entry, ok := tracker.required[key] + tracker.mu.Unlock() + if ok && now.Sub(entry.at) < humanChecksTTL { + return entry.set + } + set, known := c.requiredStatusCheckContexts(ctx, obs.Owner, obs.Repo, base) + if !known { + set = nil + } + tracker.mu.Lock() + if tracker.required == nil { + tracker.required = map[string]humanRequiredEntry{} + } + tracker.required[key] = humanRequiredEntry{at: now, set: set} + tracker.mu.Unlock() + return set } // headChecks returns the (possibly cached) check digest for obs's head. @@ -59,7 +93,7 @@ func (c *Engine) headChecks(ctx context.Context, tracker *StageTracker, key stri if ok && entry.head == obs.HeadSHA && now.Sub(entry.at) < humanChecksTTL { return entry.summary, !entry.err } - summary, err := c.summarizeChecks(ctx, obs.Owner, obs.Repo, obs.HeadSHA) + summary, err := c.summarizeChecks(ctx, obs.Owner, obs.Repo, obs.HeadSHA, func() map[string]bool { return c.headRequiredChecks(ctx, tracker, obs, now) }) if err != nil { c.warn("stage labels: check digest failed", "repo", obs.Display, "pr", obs.Number, "error", err) } @@ -492,7 +526,7 @@ func (c *Engine) humanEvidence(ctx context.Context, tracker *StageTracker, key s } e.Sentinel = hasLabelFold(obs.Labels, sentinel) summary, known := c.headChecks(ctx, tracker, key, obs, now) - e.Checks = stagelabels.CheckSummary{Total: summary.Total, Green: summary.Green, Pending: summary.Pending, Red: summary.Red, Known: known} + e.Checks = stagelabels.CheckSummary{Total: summary.Total, Green: summary.Green, Pending: summary.Pending, Red: summary.Red, Missing: summary.MissingRequired, Known: known} if c.hiveSupersedingPR(obs) { e.HiveSuperseder = true e.HiveSupersederHardStop, _ = hiveSupersederHardStop(e, contributorVerdict, c.sentinelAcknowledgedFor(obs.Owner+"/"+obs.Repo, obs.Number, obs.HeadSHA)) diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index e53d3a1cae..920de236e0 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -258,6 +258,9 @@ type StageTracker struct { ensured map[string]bool // repo → labels provisioned this process checks map[string]humanChecksEntry // key → head check digest (human routing) fences map[string]humanFenceEntry // key → head diff fence (human routing) + // required caches the base branch's required check set (human + // routing); created on first use. + required map[string]humanRequiredEntry // superseded remembers when the hive-authored superseded check last // ran per key+head, so a PR that legitimately sits at 085 is not // re-read every pass. diff --git a/src/pkg/github/automerge/automerge_stage_labels_test.go b/src/pkg/github/automerge/automerge_stage_labels_test.go index b3c34ac9fa..e6c395937e 100644 --- a/src/pkg/github/automerge/automerge_stage_labels_test.go +++ b/src/pkg/github/automerge/automerge_stage_labels_test.go @@ -186,6 +186,13 @@ func newStageAPI(t *testing.T, api *stageAPI) *httptest.Server { // before proving a new head is the hive's own base refresh. n, _ := strconv.Atoi(strings.TrimPrefix(path, "/repos/acme/widget/pulls/")) _ = json.NewEncoder(w).Encode(map[string]any{"number": n, "base": map[string]any{"ref": "main"}}) + case r.Method == http.MethodGet && strings.HasPrefix(path, "/repos/acme/widget/branches/") && strings.HasSuffix(path, "/protection/required_status_checks"): + // The human-routing check digest reads the base branch's + // required checks: none here (an unprotected branch, no rules). + w.WriteHeader(http.StatusNotFound) + _, _ = w.Write([]byte(`{"message":"Branch not protected"}`)) + case r.Method == http.MethodGet && strings.HasPrefix(path, "/repos/acme/widget/rules/branches/"): + _, _ = w.Write([]byte(`[]`)) case r.Method == http.MethodGet && strings.HasPrefix(path, "/repos/acme/widget/commits/"): // No single-commit detail is seeded: a new head is never a base // refresh here, so a recorded decision stays on its own head. diff --git a/src/pkg/github/automerge/automerge_stage_required_missing_test.go b/src/pkg/github/automerge/automerge_stage_required_missing_test.go new file mode 100644 index 0000000000..80c38ea775 --- /dev/null +++ b/src/pkg/github/automerge/automerge_stage_required_missing_test.go @@ -0,0 +1,98 @@ +package automerge + +import ( + "context" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "testing" + "time" + + hgithub "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// projectbluefin/utah#1074: a PR opened with GITHUB_TOKEN triggers no +// workflow, so the ruleset-required `contract` and `build_main / …` never +// reported, while the four checks that did run were green. The hive said +// "4/4 checks green … Ready for a human merge"; GitHub would refuse the +// merge. A required check with nothing reported is now a pending gate. +func TestHumanHandoffWaitsOnMissingRequiredChecks(t *testing.T) { + api, closeAPI := seededStageAPI(t) + defer closeAPI() + clock := &contributorLaneClock{at: time.Date(2026, 11, 2, 6, 0, 0, 0, time.UTC)} + verdict := &ContributorLaneVerdict{Configured: true, Approved: true, Verdict: "approve"} + e, store := humanStageEngine(t, api.url, clock, verdict, time.Hour) + e.checkSummary = func(context.Context, string, string, string) (hgithub.CommitChecksSummary, error) { + return hgithub.CommitChecksSummary{Total: 4, Green: 4, DCO: 1, MissingRequired: []string{"build_main / Check all testing builds successful", "contract"}}, nil + } + ctx := context.Background() + sweep := func(labels ...string) { + t.Helper() + api.reset() + e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", stagePR(9, labels...), "untrusted-author-role", false, nil) + e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", stagePR(9, labels...), contributorLaneReasonClaimTier, false, nil) + e.noteStageRole("acme", "widget", 9, stagelabels.RoleContributor) + if _, err := e.ApplyStageLabels(ctx); err != nil { + t.Fatal(err) + } + } + sweep() + clock.at = clock.at.Add(time.Hour) // soak elapsed + sweep("role/contributor", "author/human", "stage/060-reviewed") + rec, _ := store.Get(stageKey("acme", "widget", 9)) + if rec.Stage != stagelabels.Reviewed { + t.Fatalf("stage = %v, want 060 while required checks have not reported", rec.Stage) + } + for _, c := range api.comments { + if strings.HasPrefix(c, stagelabels.ReadyCommentMarker) { + t.Fatalf("posted a ready-for-human-merge comment: %q", c) + } + } + + // Once they report green, the PR is ready. + e.checkSummary = func(context.Context, string, string, string) (hgithub.CommitChecksSummary, error) { + return hgithub.CommitChecksSummary{Total: 6, Green: 6, DCO: 1}, nil + } + clock.at = clock.at.Add(humanChecksTTL) + sweep("role/contributor", "author/human", "stage/060-reviewed") + if got := stageOf(t, store, 9); got != stagelabels.ReadyForHumanMerge { + t.Fatalf("stage = %v, want 090 once the required checks reported", got) + } +} + +// The default reader asks the base branch's required set once per repo and +// branch within humanChecksTTL, and names a required check the head lacks. +func TestHeadRequiredChecksReadsBaseBranchOnce(t *testing.T) { + var protectionReads int + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/repos/acme/widget/branches/main/protection/required_status_checks": + protectionReads++ + _, _ = w.Write([]byte(`{"contexts":["contract","lint"]}`)) + case "/repos/acme/widget/commits/sha1/status": + _, _ = w.Write([]byte(`{"state":"success","statuses":[]}`)) + case "/repos/acme/widget/commits/sha1/check-runs": + _, _ = w.Write([]byte(`{"total_count":1,"check_runs":[{"name":"lint","status":"completed","conclusion":"success","app":{"id":1}}]}`)) + default: + http.NotFound(w, r) + } + })) + defer srv.Close() + client := hgithub.NewClient("token", "acme", []string{"widget"}, nil, srv.URL+"/") + now := time.Date(2026, 11, 2, 6, 0, 0, 0, time.UTC) + e := New(client, Options{Now: func() time.Time { return now }}) + tracker := NewStageTracker() + obs := stageObservation{Owner: "acme", Repo: "widget", Display: "acme/widget", Number: 1074, HeadSHA: "sha1", BaseRef: "main"} + for i := 0; i < 2; i++ { + summary, known := e.headChecks(context.Background(), tracker, stageKey("acme", "widget", 1074+i), obs, now) + if !known || !reflect.DeepEqual(summary.MissingRequired, []string{"contract"}) { + t.Fatalf("pass %d: summary = %+v known=%v, want contract missing", i, summary, known) + } + } + if protectionReads != 1 { + t.Fatalf("required set read %d times, want 1 (cached per repo and branch)", protectionReads) + } +} diff --git a/src/pkg/github/commit_checks_required_test.go b/src/pkg/github/commit_checks_required_test.go new file mode 100644 index 0000000000..ce3291523a --- /dev/null +++ b/src/pkg/github/commit_checks_required_test.go @@ -0,0 +1,44 @@ +package github + +import ( + "context" + "net/http" + "net/http/httptest" + "net/url" + "reflect" + "testing" + + gh "github.com/google/go-github/v72/github" +) + +// projectbluefin/utah#1074: every check that ran was green, and the +// ruleset-required `contract` never reported. The digest names it. +func TestSummarizeCommitChecksRequiredNamesMissing(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/repos/o/r/commits/abc/status": + _, _ = w.Write([]byte(`{"state":"success","statuses":[]}`)) + case "/repos/o/r/commits/abc/check-runs": + _, _ = w.Write([]byte(`{"total_count":2,"check_runs":[{"name":"prow / prow","status":"completed","conclusion":"success","app":{"id":1}},{"name":"lint","status":"completed","conclusion":"success","app":{"id":1}}]}`)) + default: + http.NotFound(w, r) + } + })) + defer srv.Close() + client := gh.NewClient(nil) + base, _ := url.Parse(srv.URL + "/") + client.BaseURL = base + + got, err := SummarizeCommitChecksRequired(context.Background(), client, "o", "r", "abc", map[string]bool{"contract": true, "lint": true}) + if err != nil { + t.Fatal(err) + } + if got.Green != 2 || got.Total != 2 || !reflect.DeepEqual(got.MissingRequired, []string{"contract"}) { + t.Fatalf("summary = %+v, want 2/2 green and contract missing", got) + } + got, err = SummarizeCommitChecksRequired(context.Background(), client, "o", "r", "abc", nil) + if err != nil || got.MissingRequired != nil { + t.Fatalf("no required set: %+v %v", got, err) + } +} diff --git a/src/pkg/github/commit_checks_summary.go b/src/pkg/github/commit_checks_summary.go index 9f54180230..14e7e22649 100644 --- a/src/pkg/github/commit_checks_summary.go +++ b/src/pkg/github/commit_checks_summary.go @@ -20,6 +20,12 @@ type CommitChecksSummary struct { // DCO is 1 when a DCO context succeeded, -1 when one failed, 0 when the // head carries none. DCO int + // MissingRequired names the required contexts (branch protection or + // rulesets) with no status and no check run on the head, sorted. Only + // SummarizeCommitChecksRequired fills it. A PR opened with GITHUB_TOKEN + // triggers no workflow, so its required checks never report while every + // check that did run is green (projectbluefin/utah#1074). + MissingRequired []string } // SummarizeCommitChecks reads the combined status and check runs for sha @@ -34,6 +40,20 @@ func SummarizeCommitChecks(ctx context.Context, client *gh.Client, owner, repo, return summarizeChecks(statuses, runs), nil } +// SummarizeCommitChecksRequired is SummarizeCommitChecks plus +// MissingRequired against required (nil or empty: nothing is named). +func SummarizeCommitChecksRequired(ctx context.Context, client *gh.Client, owner, repo, sha string, required map[string]bool) (CommitChecksSummary, error) { + statuses, runs, err := fetchCommitChecks(ctx, client, owner, repo, sha) + if err != nil { + return CommitChecksSummary{}, err + } + out := summarizeChecks(statuses, runs) + if len(required) > 0 { + out.MissingRequired = summarizeRequiredChecks(statuses, runs, required).Missing + } + return out, nil +} + // fetchCommitChecks reads every combined-status context and check run on sha. func fetchCommitChecks(ctx context.Context, client *gh.Client, owner, repo, sha string) ([]*gh.RepoStatus, []*gh.CheckRun, error) { if client == nil { diff --git a/src/pkg/stagelabels/human.go b/src/pkg/stagelabels/human.go index 167f89023f..b0a3a1acf8 100644 --- a/src/pkg/stagelabels/human.go +++ b/src/pkg/stagelabels/human.go @@ -70,6 +70,12 @@ type CheckSummary struct { Total, Green, Pending int // Red names every failing gating check, in a stable order. Red []string + // Missing names the required checks with nothing reported on the head. + // They are not green: GitHub refuses the merge until they report, and a + // PR whose workflows never triggered waits on them for good + // (projectbluefin/utah#1074 read "4/4 checks green, ready for a human + // merge" with `contract` and `build_main` never run). + Missing []string // Known is false when the head could not be read (API error): CI is // then a pending gate, never a pass. Known bool @@ -570,6 +576,9 @@ func RouteHuman(e Evidence) Route { case e.Checks.Pending > 0: wait = append(wait, fmt.Sprintf("%d check(s) still running", e.Checks.Pending)) } + if e.Checks.Known && len(e.Checks.Missing) > 0 { + wait = append(wait, "required check(s) `"+strings.Join(e.Checks.Missing, "`, `")+"` not reported on this head (a PR opened with GITHUB_TOKEN triggers no workflow): GitHub will not merge it until they run") + } if e.Soak > 0 && e.SoakElapsed < e.Soak { // A head the lane has NOT admitted (trust blocks it) is still // 060 while its soak runs; 095 pre-merge-soak is the lane's own @@ -657,6 +666,9 @@ func summarize(e Evidence) string { default: parts = append(parts, fmt.Sprintf("%d/%d checks green", e.Checks.Green, e.Checks.Total)) } + if e.Checks.Known && len(e.Checks.Missing) > 0 { + parts = append(parts, "required not reported: "+strings.Join(e.Checks.Missing, ", ")) + } switch e.DCO { case DCOYes: parts = append(parts, "DCO yes") diff --git a/src/pkg/stagelabels/required_missing_test.go b/src/pkg/stagelabels/required_missing_test.go new file mode 100644 index 0000000000..78335a3598 --- /dev/null +++ b/src/pkg/stagelabels/required_missing_test.go @@ -0,0 +1,25 @@ +package stagelabels + +import ( + "strings" + "testing" +) + +func TestRouteHumanMissingRequiredChecksIsAPendingGate(t *testing.T) { + e := Evidence{Head: "0c56fd61c0000000000000000000000000000000", Verdict: VerdictApproved, Cause: CauseTrust, + Checks: CheckSummary{Known: true, Total: 4, Green: 4, Missing: []string{"contract"}}, DCO: DCOYes} + r := RouteHuman(e) + if r.Stage != Reviewed { + t.Fatalf("stage = %v, want Reviewed", r.Stage) + } + if len(r.Reasons) == 0 || !strings.Contains(r.Reasons[0], "`contract` not reported on this head") { + t.Fatalf("reasons = %q", r.Reasons) + } + if !strings.Contains(r.Summary, "4/4 checks green, required not reported: contract") { + t.Fatalf("summary = %q", r.Summary) + } + e.Checks.Missing = nil + if r := RouteHuman(e); r.Stage != ReadyForHumanMerge { + t.Fatalf("stage without missing checks = %v, want 090", r.Stage) + } +}