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-18769-tracker-gate-truth.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Activity monitor: a row no longer offers **Approve**, **Request changes…** or **Let hive decide** when no decision is pending. The gate pill and its verbs now read one rule (the payload's new `human_gate`), so a PR whose reviewer sign-off a person already approved shows *Approved by @login Ā· waiting on …* naming the real blocker instead of *Needs human Ā· review*; triage and author-owned rows keep their own lead instead of a decision pill; a hold or sentinel pill on an unparked row keeps only its own answer. Required checks queued or in progress past `HIVE_TRACKER_CHECK_STUCK_AFTER` (default `2h`) read **stuck** and are named, not shown as running, and a verb clicked from a stale view says what the item is waiting on and refreshes the row ([#18769](https://github.com/hivecommons/hive/issues/18769)).
21 changes: 19 additions & 2 deletions src/docs/api-reference/dashboard-misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,29 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f

`GET /api/stage-tracker` adds independent PR `ci_activity`, `review_activity`
and `code_activity` observations, also copied to `linked_prs[]`. Each is
`{head, state, caption, detail?, actor?, source, observed_at?, since?, blocker?, url?, active?, checks_passed?, checks_total?, checks_failed?, checks_failing?, checks_pending?, perspectives_done?, perspectives_total?, perspectives?}`.
`{head, state, caption, detail?, actor?, source, observed_at?, since?, blocker?, url?, active?, checks_passed?, checks_total?, checks_failed?, checks_failing?, checks_pending?, checks_stuck?, stuck_since?, perspectives_done?, perspectives_total?, perspectives?}`.
These are display evidence, **not merge authorization**. An absent timestamp
means unknown freshness; a different head invalidates the observation.
`detail?` is the longer, plain-language sentence behind caption. `checks_failing?`
and `checks_pending?` are string lists of check names; `perspectives?` list
per-perspective verdicts on the head. CI is classified against the resolved
per-perspective verdicts on the head. `checks_stuck?` names the pending checks
that have been queued or in progress longer than `HIVE_TRACKER_CHECK_STUCK_AFTER`
(default `2h`) and `stuck_since?` is when the oldest of them started: such a
check is not running in any useful sense, and when every pending check is stuck
the caption reads `CI stuck Ā· …` and `active` is false.

Every open issue and PR row (and each `linked_prs[]` entry that mirrors a listed
PR) also carries `human_gate`: `{reasons, actions, answered?, answered_by?, waiting_on?}`.
`reasons` are the things a person is owed right now (`review`, `decision`,
`sentinel`, `hold`; empty when nothing is); `actions` are the gate verbs that
would act on the row (`decide:approve`, `gate:request-changes`, `decide:delegate`,
`gate:decide`, `gate:confirm-sentinel`, `release`) — a verb absent from the list
has nothing to act on and is never drawn. `answered` is true when the reviewer
asked for a person's sign-off on this head and the hive no longer parks the PR
on it, with `answered_by` the approver when the lane recorded one. `waiting_on`
is `{kind, text, checks?}` on a PR with no reasons: what it actually waits on
(`conflict`, `author`, `fixing`, `checks-failing`, `checks-stuck`,
`checks-missing`, `ci-running`, `review-pending`, `merge-queue`). CI is classified against the resolved
required set when branch protection is known, otherwise against every check run
observed on the head (checks_total == 0 means no count could be made). Review
assignment comes from dispatch, current work additionally requires its actual
Expand Down
21 changes: 19 additions & 2 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,13 +252,30 @@ Every row a person must settle carries exactly **one** control for it ([#17470](

| Reason | Set by | Verbs | What gets posted |
|---|---|---|---|
| `review` | the review verdict requires a human on this head (`review_activity.state: human_decision`) | **Approve** Ā· **Request changes…** Ā· **Let hive decide** | Approve posts `/lgtm` + `/approve` on the current head (`…/items/{n}/decision`, `approve`); Request changes opens a modal whose text is posted as `/hive decision <text>` (`decision: direction`), the author agent pushes a new head; Let hive decide records a `/hive decision` under the hive's policy. |
| `decision` | `stage/085-needs-decision` on a PR, `045` on an issue, or a `needs-decision` / `needs-human` modifier | **Decide…** Ā· **Approve as-is** (PR rows; *Approve* when stacked with `review`) Ā· **Let hive decide** | Decide opens a modal with the question pre-filled; the answer is posted as `/hive decision <text>`; Approve as-is is the GitHub approval of the head as it stands; Let hive decide as above. An issue with no PR offers Decide… and Let hive decide only. |
| `review` | the review verdict requires a human on this head (`review_activity.state: human_decision`) **and** the hive parks the PR on it (085 / `needs-decision` / ready for human merge) | **Approve** Ā· **Request changes…** Ā· **Let hive decide** | Approve posts `/lgtm` + `/approve` on the current head (`…/items/{n}/decision`, `approve`); Request changes opens a modal whose text is posted as `/hive decision <text>` (`decision: direction`), the author agent pushes a new head; Let hive decide records a `/hive decision` under the hive's policy. |
| `decision` | `stage/085-needs-decision` on a PR, `045` on an issue, or a `needs-decision` / `needs-human` modifier; `needs_human` alone only on a parked row | **Decide…** Ā· **Approve as-is** (PR rows; *Approve* when stacked with `review`) Ā· **Let hive decide** | Decide opens a modal with the question pre-filled; the answer is posted as `/hive decision <text>`; Approve as-is is the GitHub approval of the head as it stands; Let hive decide as above. An issue with no PR offers Decide… and Let hive decide only. |
| `sentinel` | the `sentinel-alert` label or blocking findings on this head (`sentinel_alert`, not the trusted-author notice) | **Confirm safe** Ā· **Let hive decide** | Confirm safe comments `<!-- hive:sentinel-confirmed -->` with the person's words and removes the sentinel label (`POST …/items/{n}/sentinel-confirm`, audited `repo_item_sentinel_confirm`); Let hive decide never clears the alert. |
| `hold` | a `hold` / `do-not-merge*` label (`hold`, `modifiers: hold`) | **Release hold** Ā· **Let hive decide** | Release hold removes the label (`POST …/items/{n}/hold`, `{"held": false}`); Let hive decide as above. |

Every verb runs `runRowAction` — the row menu's own path: the in-app confirm or prompt modal (never a native dialog), the result toast saying what was posted, the acting row — and the pill reads **settling…** (dashed outline, verbs disabled) until the next snapshot re-renders the row. A verb the viewer cannot run is greyed with the reason, never hidden. The review verdict's own question is not a second reason: a `requires_human` verdict on a 085 PR reads `review` alone; `review, sentinel` when the sentinel also flags it.

**The pill and its verbs read one rule** ([#18769](https://github.com/hivecommons/hive/issues/18769)). A row once showed *Needs human Ā· review* with **Approve**, **Request changes…** and **Let hive decide** while the click answered *nothing to act on — #18667 is not waiting on that decision*: the pill read the cached reviewer verdict for the head, the action read whether the hive had parked the PR on a person, and a verdict never changes for a head, so the pill outlived the approval that answered it. Now both come from the same predicate, stated by the server per row as `human_gate` (`reasons`, `actions`, `answered`, `waiting_on`) and applied by the page to the rows it draws:

| Row state | Pill | Verbs offered |
|---|---|---|
| Parked at 085 on the reviewer's sign-off question | **Needs human Ā· review** | Approve Ā· Request changes… Ā· Let hive decide |
| Parked at 085 / 045, or wearing `needs-decision` | **Needs human Ā· decision** | Decide… Ā· Approve as-is (PR rows) Ā· Let hive decide |
| `needs-human` label on a PR the hive has not parked | **Needs human Ā· decision** | Decide… only |
| Sentinel alert on a PR that is not parked | **Needs human Ā· sentinel** | Confirm safe only |
| Hold on a PR that is not parked | **Needs human Ā· hold** | Release hold only |
| Ready for human merge (090) with a sentinel alert or hold | reasons stacked as before | every verb of those reasons |
| Sign-off question answered — a person approved the head, the PR left 085 | no gate pill; a passive **Approved by @login Ā· waiting on …** pill (*No decision pending Ā· waiting on …* when the lane recorded no approver) | none |
| Triage needed, or a human author's turn (`needs_human` with no park) | no gate pill; the row's lead (**Accept triage**, **Adopt**) | the lead only |

**Let hive decide**, **Approve** and **Approve as-is** are drawn only where the action has a decision to act on (a parked PR, an issue's one parked PR, an issue parked at 045, or an issue with several open PRs for *Let hive decide*); a hold or sentinel pill on a row that is not parked keeps only its own answer. The reviewer's `requires_human` verdict lights `review` only while the hive parks the PR on it; afterwards the Review track reads *signed off* (*no sign-off pending* when the lane recorded no approver), never *needs owner sign-off*.

When no decision is pending the row names what it actually waits on (`human_gate.waiting_on`), the first that applies: a merge conflict with the base; the author's turn; required checks failing (named); required checks **stuck** (named); required checks not reported (named); CI running (*n/m*); the review re-run on the new head; the merge queue. A required check that has been queued or in progress longer than `HIVE_TRACKER_CHECK_STUCK_AFTER` (default two hours — well past the slowest pipeline) is **stuck**, not running: the CI track reads *CI 67/69 Ā· 'PR Type', 'PR Issue' stuck* (*13 running Ā· 2 stuck (…)* while other checks still move), its hover says nothing finishes a stuck check on its own, and when every pending check is stuck the track stops pulsing. A verb clicked from a stale view — the row re-rendered between the paint and the click — answers *nothing to act on — #N is waiting on required checks stuck: PR Type, PR Issue* and the tracker re-reads the server at once so the row drops the verb.

A **secondary row of a shared PR** — an issue drawn under another listed issue's row because one PR closes both ([#17333](https://github.com/hivecommons/hive/issues/17333)) — never renders a gate pill or an amber chevron of its own; its *decision pending on #N* chip is a link that scrolls to and focuses the row that carries the gate.

#### Unauthorized pill
Expand Down
1 change: 1 addition & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply
| `HIVE_CONFIG` | No | `/etc/hive/hive.yaml` | Default config path used before the `--config` flag is parsed; an explicit `--config` outranks it, so `entrypoint.sh` also appends `--config "$HIVE_CONFIG"` to the launch argv when it is set ([#4973](https://github.com/hivecommons/hive/issues/4973)). The dashboard also uses it when reporting config provenance — which is why the two must not disagree. |
| `HIVE_MODE` | No | spoke/dashboard mode | Set to `hub` to run the hub server instead of the spoke dashboard. |
| `HIVE_HUB_PORT` | No | `3001` | Hub listen port when `HIVE_MODE=hub`. |
| `HIVE_TRACKER_CHECK_STUCK_AFTER` | No | `2h` | Go duration a required check may stay queued or in progress before the activity monitor calls it **stuck** instead of running (`ci_activity.checks_stuck`, the `CI stuck Ā· …` caption and the *waiting on required checks stuck* blocker). Read on every tracker build; an unparsable or non-positive value falls back to the default. |
| `HIVE_SINGLETON_LOCK` | No | `/var/run/hive-metrics/hive.singleton.lock` when available, otherwise OS temp dir | Overrides the process singleton lock path. Set exactly `off` only for local development where duplicate processes are intentional. |
| `HIVE_GITHUB_TOKEN` | Required unless GitHub App auth is configured | none | Main PAT fallback for `github.token`; also used by fleet/stat fallback paths and some deployment manifests. Missing PAT scopes surface as request-time 403s — see [Required PAT scopes](github-app-setup.md#personal-access-token-pat-scopes). |
| `GH_APP_KEY_FILE` | No | configured `github.key_file`, then `/data/gh-app-key.pem` or `/secrets/gh-app-key.pem` in provisioned paths | GitHub App private-key file fallback. |
Expand Down
6 changes: 6 additions & 0 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -471,6 +471,10 @@ type StageTrackerItem struct {
// 095 / 100): state, what holds it, whether hive's merge sweep is on
// it now, the next pass and the soak countdown (hivecommons/hive#15073).
MergeGate *StageTrackerMergeGate `json:"merge_gate,omitempty"`
// HumanGate is the row's live human-gate state: the reasons a person is
// owed something now, the verbs that would act, and what the item
// waits on when nothing is owed (stage_tracker_gate.go).
HumanGate *StageTrackerHumanGate `json:"human_gate,omitempty"`
// Soak is the soak clock while the lane holds this head for the soak
// window, at 060/080/095: when it started, when it ends, the window
// and the head it was measured on. The SPA counts it down in place.
Expand Down Expand Up @@ -813,6 +817,8 @@ type StageTrackerLinkedPR struct {
SoakRemainingSeconds int64 `json:"soak_remaining_seconds,omitempty"`
MergeGate *StageTrackerMergeGate `json:"merge_gate,omitempty"`
MergeTrain *StageTrackerMergeTrain `json:"merge_train,omitempty"`
// HumanGate mirrors the nested PR's own row gate (stage_tracker_gate.go).
HumanGate *StageTrackerHumanGate `json:"human_gate,omitempty"`
// LeftTrain mirrors the nested PR's own row field so the sub-row's
// hover can say it left its train while under repair.
LeftTrain *StageTrackerLeftTrain `json:"left_train,omitempty"`
Expand Down
33 changes: 28 additions & 5 deletions src/pkg/dashboard/stage_tracker_activity.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@ type StageTrackerActivity struct {
// (running, queued, or not reported), so the chevron can name the last
// one or two the head waits on (hivecommons/hive#16630).
ChecksPending []string `json:"checks_pending,omitempty"`
// ChecksStuck names the pending checks that have been queued or in
// progress longer than trackerCheckStuckAfter: they are not running in
// any useful sense and will not finish on their own
// (hivecommons/hive#18769). StuckSince is when the oldest one started.
ChecksStuck []string `json:"checks_stuck,omitempty"`
StuckSince *time.Time `json:"stuck_since,omitempty"`
// Perspective counts on the current head for the Review track: Total is
// the swarm's expected set for this PR (configured perspectives plus any
// extra one dispatched or reported for the head), Done the ones with a
Expand Down Expand Up @@ -88,8 +94,8 @@ func stageTrackerCIActivity(pr github.PullRequest, now time.Time) *StageTrackerA
out.Source += "+github-commit-statuses"
}
if !a.RequiredKnown || a.RequiredSource == "" || len(a.RequiredChecks) == 0 || len(a.Required) == 0 {
stageTrackerCountHeadChecks(out, a)
out.Active = out.State == "running"
stageTrackerCountHeadChecks(out, a, now)
out.Active = out.State == "running" && !stageTrackerAllChecksStuck(out)
return out
}
type requiredObservation struct {
Expand Down Expand Up @@ -124,8 +130,8 @@ func stageTrackerCIActivity(pr github.PullRequest, now time.Time) *StageTrackerA
}
}
if !found {
stageTrackerCountHeadChecks(out, a)
out.Active = out.State == "running"
stageTrackerCountHeadChecks(out, a, now)
out.Active = out.State == "running" && !stageTrackerAllChecksStuck(out)
return out
}
}
Expand All @@ -142,6 +148,8 @@ func stageTrackerCIActivity(pr github.PullRequest, now time.Time) *StageTrackerA
// Required checks with no run at all, or only a pending commit status:
// on a Prow repository, a presubmit that never ran or has not finished.
presubmitWaiting := map[string]bool{}
// Per required-check name: when its queued or running observation began.
pendingSince := map[string]time.Time{}
// Required checks with no run on the head while commit statuses were
// not read: unknown rather than missing, with the no-run caption.
noRunUnread := map[string]bool{}
Expand Down Expand Up @@ -189,6 +197,11 @@ func stageTrackerCIActivity(pr github.PullRequest, now time.Time) *StageTrackerA
if state != "passing" && state != "failing" && state != "skipped" {
settled[name] = false
}
// Check runs only: a pending commit status carries when it was
// posted, not when a job started.
if (state == "running" || state == "queued") && check.Since != nil && check.Kind != "commit_status" {
pendingSince[name] = *check.Since
}
// A red required check leads, then missing/unknown, then running/queued.
rank := map[string]int{"passing": 0, "queued": 1, "running": 2, "skipped": 3, "unknown": 4, "missing": 5, "failing": 6}
if previous, seen := perName[name]; !seen || rank[state] >= rank[previous] {
Expand Down Expand Up @@ -328,6 +341,7 @@ func stageTrackerCIActivity(pr github.PullRequest, now time.Time) *StageTrackerA
// age rides ObservedAt for the tooltip, never a dimmer state
// (hivecommons/hive#16643).
out.Active = out.State == "running" || out.State == "queued"
stageTrackerMarkStuckChecks(out, pendingSince, now)
stageTrackerAttachTide(out, full, presubmitWaiting)
return out
}
Expand Down Expand Up @@ -419,9 +433,10 @@ func pluralVerb(n int, one, many string) string {
// when any name is red, running while names still lack a final result,
// and unknown — "no check results observed" — only when the head has no
// check run at all.
func stageTrackerCountHeadChecks(out *StageTrackerActivity, a *github.PRCIActivity) {
func stageTrackerCountHeadChecks(out *StageTrackerActivity, a *github.PRCIActivity, now time.Time) {
type tally struct {
passing, failing bool
run bool
since time.Time
}
byName := map[string]*tally{}
Expand All @@ -446,9 +461,11 @@ func stageTrackerCountHeadChecks(out *StageTrackerActivity, a *github.PRCIActivi
}
if !at.Before(t.since) {
t.since, t.passing = at, check.State == "completed" && check.Conclusion == "success"
t.run = check.Kind != "commit_status"
}
}
out.ChecksTotal = len(order)
pendingSince := map[string]time.Time{}
for _, name := range order {
t := byName[name]
switch {
Expand All @@ -459,8 +476,14 @@ func stageTrackerCountHeadChecks(out *StageTrackerActivity, a *github.PRCIActivi
out.ChecksPassed++
default:
out.ChecksPending = append(out.ChecksPending, name)
if t.run && !t.since.IsZero() {
pendingSince[name] = t.since
}
}
}
// The caller sets Active from the state on return; a head whose every
// pending check is stuck reports no motion there.
defer func() { stageTrackerMarkStuckChecks(out, pendingSince, now) }()
if out.ChecksTotal == 0 {
return
}
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_build.go
Original file line number Diff line number Diff line change
Expand Up @@ -599,6 +599,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
stageTrackerMarkClosedBy(resp.Items, s.mergedLedger().ClosedBy)
stageTrackerResolveActors(resp.Items)
stageTrackerResolveHumanAttention(resp.Items)
stageTrackerResolveHumanGates(resp.Items, now)
sort.SliceStable(resp.Items, stageTrackerLess(resp.Items))
return resp
}
Expand Down
Loading
Loading