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-for-human-merge-actions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Activity Monitor: a PR at *Ready for human merge* now offers **Approve & merge as maintainer** and **Approve — let hive merge** at the top of its ⋯ menu and needs-human popover (new `merge-now` / `queue-merge` decisions, merger/owner only, confirm + toast + decision badge), every needs-human state carries at least one matching action with a consequence line plus *Let hive decide* (on a 090 PR the hive answers at once in plain words why it won't merge, with the merge buttons), and the *untrusted author* pill explains why in plain words and how to trust the author (#15078).
16 changes: 16 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -725,6 +725,22 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p

The glyph is drawn for **every** row on the gate, so two rows in the same state always look the same; the ⬡ / 🤖 / 👤 icon *after* the word is whose move it is (`STAGE_TRACKER_ACTOR`), unchanged. The *working* spin (an agent on the item right now) stays a separate cue and now also carries its sentence as tooltip and `aria-label` (*Working now: reviewer reviewed it · 2m ago*). `next_sweep_at` comes from the automerge lanes' sweep clock (`automerge.SweepSnapshot()` — the next periodic floor pass, 5 min event-driven or the legacy 10 s tick); webhook-named passes run sooner, which the tooltip says. `last_sweep_at` is the stage record's `last_seen` (when a lane last evaluated the PR).

**Every ask has its action (the lead entries).** Owner, on hotshot#317 at *Ready for human merge · untrusted author* (2026-10-29): "this claims it needs human merge but there is no option to take that action" ([#15078](https://github.com/hivecommons/hive/issues/15078)). Whenever a row — an issue row whose one nested PR is parked, or a PR sub-row — is in a state that asks a person for something, the ⋯ menu **leads** with the matching action(s), taken straight from the payload's `decision_needed.options`, each with its consequence as the hint; the generic entries (*Decide…*, *Hold*, *Re-evaluate now*, *Mark needs-human…*, *Open on GitHub*, *Copy link*) follow under a separator, and the needs-human popover shows the same options with the consequence under each button (`ham-decision-consequences`). A Go table test (`TestStageTrackerNeedsHumanStatesCarryAnAction`) keeps every state `stageTrackerNeedsHuman` flags on a non-empty options list with at least one enabled action (or a disabled one whose `reason_if_disabled` is plain words), and renderer tests (`TestStageTrackerRowActionsLeadWithDecisionOptions`, `TestStageTrackerIssueRowWithNested090PRCarriesAllThree` — the issue row over its one nested 090 PR carries Approve & merge, Approve — let hive merge and Let hive decide) keep the menu leading with them. *Let hive decide* is on every needs-human state: where the hive cannot act it says so in plain words through the no-effect toast instead of silently recording a decision. State by state:

| State the pill shows | Lead actions in ⋯ and in the popover (consequence) |
|---|---|
| PR at 090 *Ready for human merge* (untrusted author, workflow files, manual-merge path, branch protection…) | **Approve & merge as maintainer** (merges #N into *base* now via hive's identity, attributed to you — a comment on the PR names you, the audit log records `repo_item_decision_merge`, `source: dashboard`) · **Approve — let hive merge** (records your approval as the owner decision — an APPROVE review and the automerge label; the hive's merge sweep merges it on its next pass once CI is green and the head has soaked) · Give direction (hive-authored PRs only) · Close as superseded · Close as won't fix · Hold. Both merge actions need the merger or owner role and confirm first (with *Don't ask again*); the toast reads *merged* / *queued for merge*; the badge records `merge-now` / `queue-merge`. **Let hive decide** is here too (third): on a 090 PR it never runs the policy — the hive answers at once through the no-effect toast, *I can't merge this: author @Karibhou is untrusted on hotshot — …*, with *Approve & merge as maintainer · Approve — let hive merge* as buttons and the 👥 Contributors fix in the next line. |
| PR at 085 *Needs human decision* | Let hive decide · Approve · Give direction · Close as superseded · Close as won't fix · Hold (unchanged). |
| Issue at 045 *Needs decision* (direction) | Let hive decide · Give direction · Approve direction · Send back to the hive · Hold (unchanged). |
| Human-authored PR at 071 *Needs author* / 072 *Returned to contributor* | Let hive decide · Close as superseded · Close as won't fix · Hold — the hive never rewrites a person's PR, so the choice is wait or close. (A hive-authored PR there carries *Adopt now* when adoption applies.) |
| `needs-human` label set by a person or the hive (any stage) | **Resolve — lift needs-human** (removes the label; on a PR also leaves the hive's /lgtm + /approve, on an issue a `/hive approve`) · Let hive decide · Hold. |
| `hive:unauthorized` | **Re-evaluate now** (re-reads GitHub; the hive resumes and clears the label once you did the step on GitHub) · Let hive decide · Hold · Mark needs-human. |
| 015 *Triage needed* | Accept triage · Let hive decide · Hold · Mark needs-human. |
| Hold set by an operator | **Release hold** leads; the state's own options stay listed but disabled with *Release the hold first*. |
| Any other stage the hive leaves to a person | Re-evaluate now · Let hive decide · Hold · Mark needs-human, with the question naming the stage. |

**"Untrusted author", in plain words.** The 090 pill's tooltip now says *why* and *what would make it trusted*, per reason code. For the common `contributor-lane:author-association` (hotshot#317): *Untrusted author: @login is not a collaborator of this repository on GitHub (no owner, member or collaborator association) and holds no trusted or merger tier in this hive's contributor registry, so the hive will not merge their PR unattended. To trust them: give them the trusted or merger tier under 👥 Contributors (`auto_merge.contributor_lane.require_tiers`), or add them as a collaborator of the repository on GitHub. Until then a maintainer merges — Approve & merge as maintainer, or Approve — let hive merge, from the row's ⋯ menu.* The other trust reasons (`untrusted-author-role` → merger role under ⚙ Security / `dashboard.authorized_users`; `author-permission-missing` → `auto_merge.trusted_authors.require_github_permission`; `fork-non-member`; the claim-tier / no-claim / unverified-claim family → the 👥 Contributors tier) each get their own sentence. The hive App's own PRs are never "untrusted" — the lane only names a human author; the same text is the popover's question.

**Cue tokens.** The three cues of the legend above (state pill, working spin, decision badge) share one `tracker-cues` CSS block on `.ham-row`: `--cue-state` (what the row waits on — the pill and this popover), `--cue-work` (the hive is working right now — the chevron spin), `--cue-decision` (what people and the hive decided — the ✓ badge). Nothing else blinks; motion stays in the 150–300 ms range.

### Let hive decide
Expand Down
22 changes: 22 additions & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -456,6 +456,28 @@ from **Settings → Features → Auto-merge**. The dashboard writes the same
owner-only `/api/config/auto-merge` overlay as the other auto-merge controls, so
hosted spoke changes survive restarts without editing `hive.yaml`.

**When a lane leaves the merge to a person (`stage/090-ready-for-human-merge`).**
A PR no lane vouches for — an untrusted author (`contributor-lane:author-association`,
`untrusted-author-role`, `author-permission-missing`, `fork-non-member`, the
claim-tier family), workflow files, a manual-merge path — parks at 090 with a
*Ready for human merge* pill whose tooltip names the reason and the fix in plain
words (the config key and where in ⚙ / 👥 it is set). The Activity Monitor's ⋯
menu and needs-human popover lead with the two actions that do what the pill
asks ([#15078](https://github.com/hivecommons/hive/issues/15078)), both
`POST /api/repos/{owner}/{repo}/items/{n}/decision` and both limited to a
verified owner or an authorized user with the `merger` role:

| Decision | What it does | Audit / ledger |
|---|---|---|
| `merge-now` — *Approve & merge as maintainer* | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
| `queue-merge` — *Approve — let hive merge* | Leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the App self-merge sweep, which merges on its next pass once CI is green and the head has soaked. Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *queued for merge*. |

Neither widens who the lanes trust: to stop a contributor's PRs parking at 090
give them the `trusted` / `merger` tier under 👥 Contributors
(`auto_merge.contributor_lane.require_tiers`), add them as a repository
collaborator, or list them under `dashboard.authorized_users` with the
`merger` role.

Actionable merge failures surface as dashboard system alerts, deduplicated by
repo+reason and cleared by the next successful merge in that repo. Alerts name
the operator action: grant/install the App with Contents and Pull requests write,
Expand Down
14 changes: 14 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_delegated.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"fmt"
"io"
"net/http"
"slices"
"sort"
"strconv"
"strings"
Expand Down Expand Up @@ -472,6 +473,12 @@ func (s *Server) decideDelegatedOne(ctx context.Context, repoFull string, number
s.audit.LogRecord(user, auditRepoItemDecisionDelegated+"_failed", auditDetail("repo", repoFull, "number", strconv.Itoa(number), "error", err.Error()), "", repoFull, number)
return delegatedOutcome{Err: err}
}
// A PR at 090 Ready for human merge is one the hive's lanes already
// declined to merge: no policy run changes that, so answer at once in
// plain words with the actions that do (hivecommons/hive#15078).
if out, ok := s.delegatedHumanMergeOutcome(repoFull, number, itemType, user, mergerRole, in, req); ok {
return out
}
d, deciderNotes := s.decideDelegated(ctx, in)
// An adoption whose copy was closed unmerged (hivecommons/hive#15052)
// overrides the policy: the recorded decision no longer stands, so the
Expand Down Expand Up @@ -559,6 +566,7 @@ func (s *Server) gatherDelegatedInput(ctx context.Context, repoFull string, numb
in.Labels = append(in.Labels, l.GetName())
}
author := strings.TrimSpace(issue.GetUser().GetLogin())
in.Author = author
in.HiveAuthored = client.IsHiveAuthorLogin(author)
in.TrustedAuthor = in.HiveAuthored
if issue.IsPullRequest() || itemType == "pr" {
Expand All @@ -567,7 +575,13 @@ func (s *Server) gatherDelegatedInput(ctx context.Context, repoFull string, numb
if err != nil {
return in, fmt.Errorf("reading PR %s#%d: %w", repoFull, number, err)
}
for _, l := range pr.Labels {
if name := l.GetName(); name != "" && !slices.Contains(in.Labels, name) {
in.Labels = append(in.Labels, name)
}
}
author = strings.TrimSpace(pr.GetUser().GetLogin())
in.Author = author
in.HiveAuthored = client.IsHiveAuthorLogin(author)
in.TrustedAuthor = in.HiveAuthored
if err := s.gatherDelegatedPRContext(ctx, repoFull, pr, &in); err != nil {
Expand Down
53 changes: 53 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_delegated_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -594,3 +594,56 @@ func TestDelegatedStuckWhyReadsTheLane(t *testing.T) {
}
}
}

// "Let hive decide" on a PR at 090 Ready for human merge answers at once
// (hivecommons/hive#15078): no policy run, no comment, a no-effect result
// that says in plain words why the hive will not merge it and carries the
// merge answers as buttons — enabled for a merger, greyed for a writer.
func TestDelegatedDecisionReadyForHumanMergeAnswersWithMergeOptions(t *testing.T) {
mock := &repoItemDecisionMock{prForeign: true, prLabels: []string{"stage/090-ready-for-human-merge", "role/newcomer"}}
srv := newDelegatedServer(t, mock)
body := `{"type":"pr","reason":"contributor-lane:author-association","caption":"Ready for human merge · untrusted author"}`
w := postDelegated(t, srv, 8, "writer", body, map[string]string{"X-Hive-Role": "merger"})
if w.Code != http.StatusOK {
t.Fatalf("code=%d body=%s", w.Code, w.Body.String())
}
job := decodeDelegatedJob(t, w)
if job.Status != delegatedJobStatusDone || job.Result == nil || job.Result.Action != rowActionNoEffect {
t.Fatalf("job = %+v", job)
}
res := job.Result
t.Logf("outcome: %s\nnext: %s\nwhy: %s", res.Outcome, res.Next, res.Why)
for _, want := range []string{"I can't merge this: author @someone is untrusted on testrepo", "not a collaborator", "trusted or merger tier", "👥 Contributors"} {
if !strings.Contains(res.Outcome, want) {
t.Errorf("outcome %q missing %q", res.Outcome, want)
}
}
if res.Why != delegatedecision.GlossaryHumanMerge || res.Rule != delegatedHumanMergeRule {
t.Errorf("why=%q rule=%q", res.Why, res.Rule)
}
if !strings.Contains(res.Next, "Approve & merge as maintainer · Approve — let hive merge") || !strings.Contains(res.Next, "promote the author to trusted") {
t.Errorf("next = %q", res.Next)
}
if len(res.Options) < 2 || res.Options[0].Action != decisionActionMergeNow || !res.Options[0].Enabled || res.Options[1].Action != decisionActionQueueMerge || !res.Options[1].Enabled {
t.Fatalf("options = %+v", res.Options)
}
for _, o := range res.Options {
if o.Action == decisionActionDirection && (o.Enabled || o.ReasonIfDisabled == "") {
t.Errorf("direction on a human PR must be disabled with a reason: %+v", o)
}
}
if len(mock.comments) != 0 || len(mock.edits) != 0 || len(mock.reviews) != 0 || len(mock.merges) != 0 {
t.Fatalf("nothing may be written: comments=%v edits=%v reviews=%v merges=%v", mock.comments, mock.edits, mock.reviews, mock.merges)
}

// A writer without the merger role gets the same answer with the merge
// buttons greyed and the reason in plain words.
w = postDelegated(t, srv, 8, "writer", body, nil)
job = decodeDelegatedJob(t, w)
if job.Result == nil || len(job.Result.Options) < 2 {
t.Fatalf("job = %+v", job)
}
if o := job.Result.Options[0]; o.Enabled || o.ReasonIfDisabled != decisionWhyMergerRole {
t.Errorf("merge-now for a writer = %+v", o)
}
}
Loading
Loading