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-required-checks-missing.md
Original file line number Diff line number Diff line change
@@ -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.
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 @@ -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
Expand Down
42 changes: 38 additions & 4 deletions src/pkg/github/automerge/automerge_stage_human.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
}
Expand Down Expand Up @@ -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))
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/github/automerge/automerge_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 7 additions & 0 deletions src/pkg/github/automerge/automerge_stage_labels_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
98 changes: 98 additions & 0 deletions src/pkg/github/automerge/automerge_stage_required_missing_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
44 changes: 44 additions & 0 deletions src/pkg/github/commit_checks_required_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
20 changes: 20 additions & 0 deletions src/pkg/github/commit_checks_summary.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 {
Expand Down
12 changes: 12 additions & 0 deletions src/pkg/stagelabels/human.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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")
Expand Down
25 changes: 25 additions & 0 deletions src/pkg/stagelabels/required_missing_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
Loading