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-ready-comment-behind-base.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The 090 "Ready for a human merge" comment no longer says "Blocked only by" the author's trust tier when GitHub reports the head behind a base that requires up-to-date branches: it names the base merge as a second blocker and stops offering "(or merge)" (projectbluefin/common#1619).
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 @@ -52,12 +52,12 @@ hub read that store and nothing else (`stageStoreOrShared`,
`SyncIssueStageLabels` (`src/pkg/github/issue_stage_labels.go:205`,
`src/pkg/github/issue_stage_labels.go:337`) from the enumeration bucket. PRs
are staged by the automerge engine: each lane calls `recordStage`
(`src/pkg/github/automerge/automerge_stage_labels.go:552`), observations are
(`src/pkg/github/automerge/automerge_stage_labels.go:555`), observations are
sorted by `stageLanePrecedence` (self 3 > trusted 2 > contributor 1,
`src/pkg/github/automerge/automerge_stage_labels.go:245`), each is classified
by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:344`)
into a ranked opinion (`prstage.RankNone..prstage.RankOwned`,
`src/pkg/stageengine/prstage/types.go:145-148`), and
`src/pkg/stageengine/prstage/types.go:216-219`), and
`ResolveStage` picks the winner
(`src/pkg/stageengine/derive_pr_classify.go:720`). These PR helpers now
live in the engine (#13779); automerge keeps only gathering-side previews. Shared concepts —
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 @@ -465,7 +465,7 @@ conflict reason and the contributor lane's soak — and
| 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, 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)." |
| 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)." When GitHub reports the head behind a base that requires up-to-date branches, the stage is still 090, but the comment adds "behind `main`" to the digest, says "Blocked by" instead of "Blocked only by", and says GitHub will not merge the head until `main` is merged into it ([projectbluefin/common#1619](https://github.com/projectbluefin/common/issues/1619)) |

The entry comments are posted once per stage visit (a flip 085 ↔ 090 is a
new visit) and never as a GitHub review: the hive does not approve on a
Expand Down
86 changes: 86 additions & 0 deletions src/pkg/github/automerge/automerge_stage_behind_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
package automerge

import (
"context"
"strings"
"testing"
"time"

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

// projectbluefin/utah#1072: a contributor PR whose only lane objection is
// trust, every check green, but GitHub reports the head BEHIND a `main`
// that requires up-to-date branches. The lane's fresh PR fetch carries the
// mergeable_state to the stage pass, and the 090 comment names the base
// merge instead of "Blocked only by".
func TestReadyCommentNamesBehindBaseFromLaneFetch(t *testing.T) {
api, closeAPI := seededStageAPI(t)
defer closeAPI()
clock := &contributorLaneClock{at: time.Date(2026, 11, 6, 15, 0, 0, 0, time.UTC)}
verdict := &ContributorLaneVerdict{Configured: true, Approved: true, Verdict: "approve"}
e, store := humanStageEngine(t, api.url, clock, verdict, time.Hour)
ctx := context.Background()
sweep := func(state string, labels ...string) {
t.Helper()
api.reset()
pr := stagePR(9, labels...)
pr.Base = &gh.PullRequestBranch{Ref: gh.Ptr("main")}
pr.MergeableState = gh.Ptr(state)
e.noteStagePR("acme", "widget", 9, pr)
e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", pr, "untrusted-author-role", false, nil)
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, contributorLaneReasonClaimTier, false, nil)
e.noteStageRole("acme", "widget", 9, stagelabels.RoleContributor)
if _, err := e.ApplyStageLabels(ctx); err != nil {
t.Fatal(err)
}
}
sweep("behind")
clock.at = clock.at.Add(time.Hour) // soak elapsed
sweep("behind", "role/contributor", "author/human", "stage/060-reviewed")
if got := stageOf(t, store, 9); got != stagelabels.ReadyForHumanMerge {
t.Fatalf("stage = %v, want 090: behind does not change the stage", got)
}
if len(api.comments) != 1 || !strings.HasPrefix(api.comments[0], stagelabels.ReadyCommentMarker) {
t.Fatalf("comments = %q, want one 090 entry comment", api.comments)
}
got := api.comments[0]
for _, want := range []string{"3/3 checks green, DCO yes, behind `main`", "Blocked by `role/contributor` (below require_tiers).", "GitHub will not merge this head until `main` is merged into it."} {
if !strings.Contains(got, want) {
t.Fatalf("comment lacks %q:\n%s", want, got)
}
}
if strings.Contains(got, "Blocked only by") || strings.Contains(got, "(or merge)") {
t.Fatalf("comment still calls trust the only blocker:\n%s", got)
}
}

// The mergeable_state a lane read is only evidence for the head it was read
// on: a state noted for an older head never reaches the observation of a
// newer one, and a clean state is not "behind".
func TestHumanBehindBaseOnlyForTheFetchedHead(t *testing.T) {
tracker := NewStageTracker()
e := New(nil, Options{StageLabelPolicy: func() StageLabelPolicy { return StageLabelPolicy{Enabled: true} }, StageTracker: tracker})
old := stagePR(7)
old.Head.SHA = gh.Ptr("old")
old.MergeableState = gh.Ptr("behind")
e.noteStagePR("acme", "widget", 7, old)
tracker.record(stageObservation{Lane: stageLaneContributor, Owner: "acme", Repo: "widget", Number: 7, HeadSHA: "new", BaseRef: "main"})
cur := stagePR(8)
cur.MergeableState = gh.Ptr("BEHIND")
e.noteStagePR("acme", "widget", 8, cur)
tracker.record(stageObservation{Lane: stageLaneContributor, Owner: "acme", Repo: "widget", Number: 8, HeadSHA: "sha", BaseRef: "main"})
clean := stagePR(10)
clean.MergeableState = gh.Ptr("clean")
e.noteStagePR("acme", "widget", 10, clean)
tracker.record(stageObservation{Lane: stageLaneContributor, Owner: "acme", Repo: "widget", Number: 10, HeadSHA: "sha", BaseRef: "main"})
want := map[int]string{7: "", 8: "main", 10: ""}
for _, list := range tracker.drain() {
for _, obs := range list {
if got := humanBehindBase(obs); got != want[obs.Number] {
t.Fatalf("pr %d: humanBehindBase = %q, want %q (detail %+v)", obs.Number, got, want[obs.Number], obs.Detail)
}
}
}
}
17 changes: 17 additions & 0 deletions src/pkg/github/automerge/automerge_stage_human.go
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,22 @@ func humanConflict(obs stageObservation) bool {
obs.AuthorKind == authorkind.Human && humanConflictReasons[obs.LaneReason]
}

// humanBehindBase names obs's base branch when a lane's fresh PR fetch this
// cycle read GitHub's mergeable_state "behind" for exactly this head, and
// "" otherwise. GitHub reports "behind" only when the base requires
// up-to-date branches, so a human merge is refused until the base is merged
// in; the 090 comment says so instead of calling trust the only blocker
// (projectbluefin/common#1619, utah#1072).
func humanBehindBase(obs stageObservation) string {
if obs.HeadSHA == "" || obs.Detail.MergeableStateHead != obs.HeadSHA || obs.Detail.MergeableState != "behind" {
return ""
}
if base := strings.TrimSpace(obs.BaseRef); base != "" {
return base
}
return "base"
}

// supersededCheckTTL bounds how often the hive-authored superseded check
// re-reads a PR that stays parked on a person at the same head.
const supersededCheckTTL = humanChecksTTL
Expand Down Expand Up @@ -491,6 +507,7 @@ func (c *Engine) humanEvidence(ctx context.Context, tracker *StageTracker, key s
if requester := strings.TrimSpace(obs.Detail.HumanChangeRequester); requester != "" && obs.HeadSHA != "" && strings.TrimSpace(obs.Detail.HumanChangeRequestHead) == obs.HeadSHA {
e.HumanChangeRequester = requester
}
e.BehindBase = humanBehindBase(obs)
if obs.Reason == autoMergeReasonMergeRefusedReview {
// GitHub wants an approving review, and someone's change request
// still stands: the ask is that reviewer's re-review, not an
Expand Down
8 changes: 8 additions & 0 deletions src/pkg/github/automerge/automerge_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -421,6 +421,9 @@ func (t *StageTracker) drain() [][]stageObservation {
o.Detail.DCOGate, o.Detail.DCOGateHead = detail.DCOGate, detail.DCOGateHead
o.Detail.SquashSignoffGate = detail.SquashSignoffGate
}
if detail.MergeableStateHead != "" && detail.MergeableStateHead == o.HeadSHA {
o.Detail.MergeableState, o.Detail.MergeableStateHead = detail.MergeableState, detail.MergeableStateHead
}
list = append(list, o)
}
sort.Slice(list, func(i, j int) bool { return stageLanePrecedence[list[i].Lane] > stageLanePrecedence[list[j].Lane] })
Expand Down Expand Up @@ -703,9 +706,14 @@ func (c *Engine) noteStagePR(owner, repo string, number int, pr *gh.PullRequest)
return
}
comments := pr.GetComments() + pr.GetReviewComments()
mergeableState := strings.ToLower(strings.TrimSpace(pr.GetMergeableState()))
head := strings.TrimSpace(pr.GetHead().GetSHA())
c.stageTrackerOrShared().note(stageKey(owner, repo, number), func(d *stageDetail) {
// A fresh fetch already includes any comment credited before it.
d.Comments, d.CommentsKnown, d.OwnComments = comments, true, 0
if head != "" {
d.MergeableState, d.MergeableStateHead = mergeableState, head
}
})
}

Expand Down
38 changes: 38 additions & 0 deletions src/pkg/github/commit_checks_required_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,41 @@ func TestSummarizeCommitChecksRequiredNamesMissing(t *testing.T) {
t.Fatalf("no required set: %+v %v", got, err)
}
}

// A required job skipped by its `if:` reports conclusion "skipped", which
// GitHub accepts as passing for a required check: it is reported, not
// missing. A required check still queued is reported too (pending), and only
// a context with no status and no check run at all is missing
// (projectbluefin/common#1619).
func TestSummarizeCommitChecksRequiredSkippedAndPendingAreReported(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":3,"check_runs":[` +
`{"name":"Canary","status":"completed","conclusion":"skipped","app":{"id":15368}},` +
`{"name":"Unit tests","status":"queued","app":{"id":15368}},` +
`{"name":"report","status":"completed","conclusion":"success","app":{"id":15368}}]}`))
default:
http.NotFound(w, r)
}
}))
defer srv.Close()
client := gh.NewClient(nil)
base, _ := url.Parse(srv.URL + "/")
client.BaseURL = base

required := map[string]bool{"Canary": true, "Unit tests": true, "Runtime contract": true}
got, err := SummarizeCommitChecksRequired(context.Background(), client, "o", "r", "abc", required)
if err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got.MissingRequired, []string{"Runtime contract"}) {
t.Fatalf("missing = %q, want only the never-reported Runtime contract", got.MissingRequired)
}
if got.Total != 3 || got.Green != 2 || got.Pending != 1 || len(got.Red) != 0 {
t.Fatalf("summary = %+v, want 3 checks: skipped and success green, one pending", got)
}
}
8 changes: 8 additions & 0 deletions src/pkg/stageengine/prstage/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,14 @@ type Detail struct {
// there. Only repositories that carry that workflow run it, so the
// sign-off attribution notes name it only where it is.
SquashSignoffGate bool
// MergeableState is GitHub's mergeable_state ("behind", "clean",
// "blocked", …, lower-cased; "" when unknown) from a lane's fresh PR
// fetch this cycle, for MergeableStateHead only. GitHub reports
// "behind" only when the base requires up-to-date branches, so the
// 090 entry comment names it instead of calling trust the only
// blocker (projectbluefin/common#1619).
MergeableState string
MergeableStateHead string
}

// RedCheck returns the first red non-required check on head, or "".
Expand Down
47 changes: 43 additions & 4 deletions src/pkg/stagelabels/human.go
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,13 @@ type Evidence struct {
// problem with the PR itself.
HiveSuperseder bool
HiveSupersederHardStop string
// BehindBase names the base branch when GitHub reports the head
// "behind" it ("" otherwise). GitHub says "behind" only when the base
// requires up-to-date branches, so GitHub will not merge this head until
// the base is merged in: the 090 comment names it instead of calling trust
// the only blocker (projectbluefin/common#1619). It never changes the
// stage: the trust decision is still the person's to make.
BehindBase string
}

// Hard-stop tokens for a hive-authored superseding PR: the only reasons
Expand Down Expand Up @@ -318,6 +325,9 @@ type Route struct {
// Hold carries the `hold` provenance into the 085 comment so it can
// name who set the hold and offer release / keep (hivecommons/hive#15020).
Hold *HoldProvenance
// BehindBase is Evidence.BehindBase on a trust-blocked 090: the 090
// comment then says the branch must be brought up to date as well.
BehindBase string
}

// Lane-vocabulary reasons RouteHuman emits for the fixing stages.
Expand Down Expand Up @@ -623,7 +633,7 @@ func RouteHuman(e Evidence) Route {
}
return route
}
return Route{Stage: ReadyForHumanMerge, Summary: summary, HumanApprover: approver}
return Route{Stage: ReadyForHumanMerge, Summary: summary, HumanApprover: approver, BehindBase: strings.TrimSpace(e.BehindBase)}
}

// decisionQuestionPlaceholderMentionRE matches the policy example's
Expand Down Expand Up @@ -692,6 +702,9 @@ func summarize(e Evidence) string {
if e.Conflict {
parts = append(parts, "merge conflict")
}
if base := strings.TrimSpace(e.BehindBase); base != "" {
parts = append(parts, "behind `"+base+"`")
}
if e.Soak > 0 {
if e.SoakElapsed >= e.Soak {
parts = append(parts, "soak "+e.Soak.Round(time.Minute).String()+" elapsed")
Expand Down Expand Up @@ -753,7 +766,9 @@ func EntryCommentUpdated(body string, at time.Time) string {
// DCO yes, soak 2h elapsed. Blocked only by `role/newcomer` (below
// require_tiers).
//
// blockedBy is the prose for the trust cause ("" when unknown).
// blockedBy is the prose for the trust cause ("" when unknown). A head
// behind a base that requires up-to-date branches (r.BehindBase) reads
// "Blocked by …" and names the base merge as well (readyCommentBehindTail).
//
// An approved manual-merge route (r.ManualMerge) names the lane rule and
// the approver instead of a trust cause, and tells the person the one step
Expand Down Expand Up @@ -782,14 +797,38 @@ func ReadyComment(r Route, blockedBy string) string {
return b.String()
}
if blockedBy = strings.TrimSpace(blockedBy); blockedBy != "" {
b.WriteString(" Blocked only by ")
b.WriteString(readyCommentBlockedLead(r))
b.WriteString(blockedBy)
b.WriteString(".")
}
b.WriteString("\n\n<sub>The hive never approves on your behalf: `/lgtm` `/approve` (or merge) if you accept it.</sub>")
b.WriteString(readyCommentBehindTail(r))
return b.String()
}

// readyCommentBlockedLead opens the trust clause of the 090 comment. Trust
// is the only blocker unless the head is behind a base that requires
// up-to-date branches (projectbluefin/common#1619).
func readyCommentBlockedLead(r Route) string {
if strings.TrimSpace(r.BehindBase) != "" {
return " Blocked by "
}
return " Blocked only by "
}

// readyCommentBehindTail ends the trust-blocked 090 comment. A head behind
// a base that requires up-to-date branches is one GitHub will not merge
// until the base is merged in, so the comment says so and no longer offers
// "(or merge)" (projectbluefin/utah#1072 read "Blocked only by
// `role/untrusted`" while BEHIND).
func readyCommentBehindTail(r Route) string {
base := strings.TrimSpace(r.BehindBase)
if base == "" {
return "\n\n<sub>The hive never approves on your behalf: `/lgtm` `/approve` (or merge) if you accept it.</sub>"
}
return " The branch is also behind `" + base + "`, which requires up-to-date branches: GitHub will not merge this head until `" + base + "` is merged into it." +
"\n\n<sub>The hive never approves on your behalf: `/lgtm` `/approve` if you accept it; the branch still has to be brought up to date before it can merge.</sub>"
}

// DecisionComment renders the 085 entry comment naming what is owed.
func DecisionComment(r Route) string {
var b strings.Builder
Expand Down
66 changes: 66 additions & 0 deletions src/pkg/stagelabels/ready_behind_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
package stagelabels

import (
"strings"
"testing"
)

// projectbluefin/utah#1072 (head c38126c, 2026-11-06/07): every required
// check was green, but GitHub reported the head BEHIND a `main` that
// requires up-to-date branches, and the 090 comment still said "Blocked
// only by `role/untrusted`" and offered "(or merge)". The comment now names
// the base merge as a second blocker; the stage stays 090.
func TestReadyCommentNamesBehindBase(t *testing.T) {
e := Evidence{Head: "c38126c79dc536223897c2a99fdf9cb105f5254a", Verdict: VerdictApproved, Cause: CauseTrust,
Checks: CheckSummary{Known: true, Total: 20, Green: 20}, BehindBase: "main"}
r := RouteHuman(e)
if r.Stage != ReadyForHumanMerge {
t.Fatalf("stage = %v, want 090: behind is not a stage of its own", r.Stage)
}
if r.BehindBase != "main" {
t.Fatalf("route BehindBase = %q, want main", r.BehindBase)
}
if !strings.Contains(r.Summary, "20/20 checks green, behind `main`") {
t.Fatalf("summary = %q", r.Summary)
}
got := ReadyComment(r, "`role/untrusted` (no verified hive claim or registry tier)")
for _, want := range []string{
"Blocked by `role/untrusted` (no verified hive claim or registry tier).",
"The branch is also behind `main`, which requires up-to-date branches: GitHub will not merge this head until `main` is merged into it.",
"`/lgtm` `/approve` if you accept it; the branch still has to be brought up to date before it can merge.",
} {
if !strings.Contains(got, want) {
t.Fatalf("comment lacks %q:\n%s", want, got)
}
}
for _, unwanted := range []string{"Blocked only by", "(or merge)"} {
if strings.Contains(got, unwanted) {
t.Fatalf("comment still says %q while behind:\n%s", unwanted, got)
}
}

// Up to date: the comment reads exactly as before.
e.BehindBase = ""
r = RouteHuman(e)
got = ReadyComment(r, "`role/untrusted` (no verified hive claim or registry tier)")
if r.BehindBase != "" || strings.Contains(r.Summary, "behind") ||
!strings.Contains(got, "Blocked only by `role/untrusted` (no verified hive claim or registry tier).") ||
!strings.Contains(got, "`/lgtm` `/approve` (or merge) if you accept it.") {
t.Fatalf("up-to-date comment changed:\n%s", got)
}
}

// A behind head whose required checks have not reported still waits at 060
// on the checks (projectbluefin/utah#1074): the behind note never lifts a
// head to 090.
func TestRouteHumanBehindWithMissingRequiredStillWaits(t *testing.T) {
e := Evidence{Head: "0c56fd61c0000000000000000000000000000000", Verdict: VerdictApproved, Cause: CauseTrust,
Checks: CheckSummary{Known: true, Total: 4, Green: 4, Missing: []string{"contract"}}, BehindBase: "main"}
r := RouteHuman(e)
if r.Stage != Reviewed {
t.Fatalf("stage = %v, want 060 while a required check has not reported", r.Stage)
}
if !strings.Contains(r.Summary, "required not reported: contract") || !strings.Contains(r.Summary, "behind `main`") {
t.Fatalf("summary = %q", r.Summary)
}
}
Loading