Skip to content
Closed
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-18866-sha-hold-visibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Exempt trusted and code-specific bug reports from SHA holds, show work-blocking labels on dashboard issue rows, and let authorized maintainers persistently override a SHA hold.
1 change: 1 addition & 0 deletions src/docs/dashboard-copy-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ The new hover, verbatim (title line omitted):
| Confirm: Merge now as maintainer | dialog | 76 | 53 | same |
| ⋯ menu hints (`stageTrackerLeadActions` → `ham-menu-hint`) | ⋯ menu | server consequences (11–31 each) | server consequences (≤ 12 each) | Go budget test |
| `stageTrackerOpenTriageNeeded` → `stageTrackerSegments` / `stageTrackerHeadline` Open word (`tracker-row.js`, `tracker-words.js`) | Open chevron, chevron hover first word, row tooltip headline | *New · since 28m* on a reporter-trust hold; the ask lived only in the caption ([#15437](https://github.com/hivecommons/hive/issues/15437)) | *Triage needed · since 28m* (same word as the `needs-triage` chip / 015) | `TestStageTrackerNewRowRendering`, `TestStageTracker_ReporterTrustHoldReadsTriageNeeded` |
| `stageTrackerControlLabels` (`tracker-row-strip.js`) | issue control-label pills and Open chevron hover | A SHA-gated issue could look merely open | The label names the gate; hover explains the reason and how to lift it. For SHA holds, add the affected commit SHA to the issue or a comment for the sweep to remove the label, or use **Override SHA hold** with hold-release permission. The override does not release other holds. | `stage_tracker_control_labels.test.js`, `TestStageTrackerSHAControlLabel` |
| `stageTrackerTriageNeededCaption` (`stageTrackerCaption` 015, `stageTrackerNewState` hold text) | row caption, feed | 110 ("Actionable, but no maintainer has looked at it yet; waiting for triage — triage needed: carries needs triage": *triage* ×3 after the chevron word) / 84 ("New · waiting for a maintainer's triage (add `triage/accepted`); the hive's next pass in 7m") | 31 ("Triage needed — accept or close"; the next-mover and next-pass narration stay on the chevron hover) | `TestStageTracker_TriageNeededStage`, `TestStageTracker_ReporterTrustHoldReadsTriageNeeded`, `TestStageTrackerNewState` |
| `stageTrackerLeadActionHtml` (`tracker-actions.js`) | the row header's inline lead button (chip slot) | — (the lead sat in the ⋯ menu only) | the menu entry's label (1–4), its hint as the hover | `TestStageTrackerLeadActionInline`, `TestStageTrackerMaintainerRowsHaveLeadAction` |
| Toasts (`STAGE_TRACKER_ACTING_CAPTIONS`, acted labels) | toast | 2–4 each | unchanged | — |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ Some sweeps list items themselves. They still use the same hold predicate (`Clie

- Auto-merge sweeps use `Transport.IsHeldLabels`. The queued (`lgtm`) sweep skips a held PR before fetching it; the self-authored sweep skips held PRs and `needs-human` before merge (`src/pkg/github/automerge/automerge_sweep.go:23-38`, `src/pkg/github/automerge/automerge_sweep.go:954-959`, `src/pkg/github/automerge/automerge_sweep_loop.go:13-48`, `src/pkg/github/automerge/automerge_sweep_loop.go:73-92`).
- The task-list sweep skips held issues before its exempt / issue `needs-human` gate. It does not comment on, relabel or close them (`src/pkg/github/task_list_sweep.go:848-854`).
- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold`, and `needs-sha` keeps agents off the issue until it is removed (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`).
- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice, except for owner/maintainer or Hive authors, bodies citing concrete paths, and issues with the persistent `hive/sha-override` label. It never applies `hold`; `needs-sha` keeps agents off the issue until removed. On exemption it removes a SHA label only when its newest label event was by the App, and removes a legacy hard hold only when also paired with the App-authored SHA notice (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`).
- PR-request watching applies server-side holds after creation; the wrapper discards an agent's `--label hold` (`src/pkg/github/pr_request_watcher.go:452-524`, `bin/hive-open-pr.sh:142-150`).

Policy templates also say to respect `hold`, `on-hold`, `hold/review`, `hive-pause/<hive-id>`, any label containing `hold`, and exempt `do-not-merge`. That instruction is a prompt-level backstop; enumeration and sweep checks are the hard enforcement.
Expand Down
6 changes: 3 additions & 3 deletions src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ Commit committer dates and SHA-keyed `check_suite` / `status` times are never us

**Applies to:** Issues. **Kind:** Hard issue hold.

Since [#18468](https://github.com/hivecommons/hive/issues/18468) the sweep gives every reporter the `needs-sha` label below and never applies `hold`; `needs-sha` itself keeps the issue out of agent work with reporter trust on or off. Before that, human-filed primary-repo `kind/bug` without a 7-40 hex SHA got `hold` and a notice carrying `<!-- hive:sha-hold -->`; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002).
Since [#18468](https://github.com/hivecommons/hive/issues/18468) the sweep never applies `hold`. Before that, human-filed primary-repo `kind/bug` without a 7-40 hex SHA got `hold` and a notice carrying `<!-- hive:sha-hold -->`. Hive removes a legacy SHA hold when a SHA appears or the issue is exempt, only if the newest `hold` event was labeled by the App bot and paired with an App-authored notice at or after it. A human's hold, a re-hold, or another subsystem's hold stays.

The hard-suppress reconcile also lifts this `hold` once a PR referencing the issue merges after it was applied.

Expand All @@ -207,13 +207,13 @@ The hard-suppress reconcile also lifts this `hold` once a PR referencing the iss

**Applies to:** Issues. **Kind:** Hard (issue gate; not a PR merge gate).

A `kind/bug` without a SHA gets this label plus the `<!-- hive:sha-hold -->` notice. While it is on the issue no agent implements, decomposes or claims it, whatever the reporter-trust setting; the issue shows as filtered in the work list. The sweep removes it once a SHA appears, which releases the issue. Description: "Waiting on the reporter for the commit SHA; hive won't work this until it's added."
An external primary-repo `kind/bug` without a SHA in its body or comments gets this label plus the `<!-- hive:sha-hold -->` notice. Issues authored by an OWNER, MEMBER, COLLABORATOR or Hive's own accounts, and issues whose body cites a concrete file or code path, are exempt. While the label is present no agent implements, decomposes or claims the issue, whatever the reporter-trust setting. The sweep removes its own existing label when an exemption applies; it leaves a human-applied label alone. The dashboard shows blocking control labels and explains how to lift them.

**Who applies it:** Hive.

**Checked by:** SHA-hold sweep. **When:** Eval tick SHA sweep.

**Release or override.** Add SHA evidence, or remove the label
**Release or override.** Post a commit SHA, or use the authorized dashboard override. The override records `hive/sha-override` on the issue so subsequent sweeps do not re-add the SHA hold. Other hold labels still apply.

**Configuration and implementation.** `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` is treated as unset, since the sweep never applies `hold`)

Expand Down
2 changes: 1 addition & 1 deletion src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ Top-level YAML keys accepted by `config.Config`:
| `dedupe.advisory_autoclose` | `true`. | The close-on-merge backfill works the dedupe agent's advisory checklists itself ([#15754](https://github.com/hivecommons/hive/issues/15754)): for every open hive-authored issue whose body opens with `<!-- hive:dedupe-checklist repo=… -->` it ticks each `- [ ] #N …` task line whose #N is closed or merged (one body edit per sweep, idempotent) and, once every line is ticked, comments `All N items resolved (#a closed, #b merged …) — closing this advisory.` and closes the issue as `completed`. A checklist with open items expires after seven days. The Activity Monitor never parks an advisory at 045 regardless. `false` leaves checklists untouched (they still expire). Env/dashboard: yaml-only. |
| `issues.close_on_merge_recheck` | `24h`. | How long a merged-PR claim keeps its settled close-on-merge verdict before the ledger sweep re-verifies it against the API. Once a sweep reaches a final verdict for a claim — issue closed, already closed, Hive marker present, awaiting confirmation, untrusted author, reopened by a person, or PR not merged — it stamps `close_on_merge_settled_at` on the claim and later sweeps skip the claim with no API call until this window elapses. Transient failures (issue, timeline or comment reads/writes that errored) never settle and retry on the next sweep as before. The marker follows the claim while the same PR claims the issue and resets when a different PR takes it over. Env override: `HIVE_CLOSE_ON_MERGE_RECHECK` (Go duration). |
| `issues.reporter_confirmation` | `false`. | Legacy opt-in switch for hives that want every human-filed bug-family issue to wait for reporter verification before close. Leave false for the default close-on-merge policy; add `hive: needs-confirmation` to an individual issue when only that issue needs the gate. `hive: reporter-confirmed` and `hive: close-on-merge` remain accepted legacy bypasses. |
| `issues.sha_hold_trusted_label` | `needs-sha`. | Soft label the SHA-hold sweep applies to a `kind/bug` without a commit SHA when the reporter's author association is in `project.issue_filter.reporter_trust.trusted_associations` (default OWNER/MEMBER/COLLABORATOR), instead of the hard `hold` (#12002). The label keeps the issue out of agent work until it is removed. A SHA-hold `hold` already on such an issue is swapped for this label. Set to `hold` to restore the hard hold for every reporter. |
| `issues.sha_hold_trusted_label` | `needs-sha`. | Label applied to primary-repo `kind/bug` issues without a SHA, except those from OWNER/MEMBER/COLLABORATOR or Hive authors, and those naming concrete files or code paths. The label blocks agent work until a SHA is supplied or an authorized dashboard user overrides it; the persistent `hive/sha-override` label prevents reapplication. Exempt issues have sweep-owned labels removed; human holds remain. Setting this to `hold` uses the default `needs-sha` instead. |
| `issues.lift_hive_hard_suppress` | `true`. | Runs the hard-suppress reconcile (#12002): a `hold` or `blocked` label on an open issue is lifted when Hive provably applied it (newest label event is a `labeled` by the App bot; for `hold`, paired with the `<!-- hive:sha-hold -->` notice) and a PR cross-referencing the issue merged after it. Hive posts one note carrying `<!-- hive:hard-suppress-lifted -->`. Human-applied labels are never lifted. Skipped with the other unstick steps when the API budget is critical. |
| `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. |
| `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `<!-- hive:rfc-existing-coverage -->` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:5369-5379`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5417-5427`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes → refactors/docs → tests).
Expand Down
57 changes: 55 additions & 2 deletions src/pkg/dashboard/api_repo_hold.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@ import (
const repoHoldPermissionCacheTTL = 2 * time.Minute

type repoHoldRequest struct {
Held bool `json:"held"`
Type string `json:"type"`
Held bool `json:"held"`
Type string `json:"type"`
OverrideSHA bool `json:"override_sha"`
}

type repoHoldResponse struct {
Expand Down Expand Up @@ -672,6 +673,14 @@ func (s *Server) handleRepoItemHold(w http.ResponseWriter, r *http.Request) {
if s.deps.Ctx != nil {
ctx = s.deps.Ctx
}
if body.OverrideSHA {
if body.Held || !strings.EqualFold(body.Type, "issue") {
jsonError(w, "SHA override requires an issue release", http.StatusBadRequest)
return
}
s.overrideRepoSHAHold(w, r, ctx, owner, repoName, number)
return
}
canonical := s.canonicalHoldLabel()
repoFull := owner + "/" + repoName
var removed []string
Expand Down Expand Up @@ -724,3 +733,47 @@ func (s *Server) handleRepoItemHold(w http.ResponseWriter, r *http.Request) {
Result: result,
})
}

// overrideRepoSHAHold records the operator's decision before removing the
// SHA label, so subsequent sweeps can honor the override.
func (s *Server) overrideRepoSHAHold(w http.ResponseWriter, r *http.Request, ctx context.Context, owner, repo string, number int) {
repoFull := owner + "/" + repo
labels, err := s.currentItemLabels(ctx, owner, repo, number)
if err != nil {
s.repoHoldGitHubError(w, "read labels", repoFull, number, "", err)
return
}
shaLabel := "needs-sha"
if s.deps.Config != nil {
if configured := s.deps.Config.Issues.EffectiveSHAHoldTrustedLabel(); configured != "" && !strings.EqualFold(configured, "hold") {
shaLabel = configured
}
}
var removed []string
for _, label := range labels {
if strings.EqualFold(label, shaLabel) || strings.EqualFold(label, "needs-sha") {
removed = append(removed, label)
}
}
if len(removed) > 0 {
if err := s.deps.GHClient.EnsureIssueLabel(ctx, repoFull, github.SHAHoldOverrideLabel, "0e8a16", "A maintainer waived the SHA requirement for this issue."); err != nil {
s.repoHoldGitHubError(w, "ensure SHA override label", repoFull, number, github.SHAHoldOverrideLabel, err)
return
}
if err := s.deps.GHClient.AddLabels(ctx, repoFull, number, []string{github.SHAHoldOverrideLabel}); err != nil {
s.repoHoldGitHubError(w, "add SHA override label", repoFull, number, github.SHAHoldOverrideLabel, err)
return
}
for _, label := range removed {
if err := s.deps.GHClient.RemoveLabel(ctx, repoFull, number, label); err != nil {
s.repoHoldGitHubError(w, "remove SHA hold label", repoFull, number, label, err)
return
}
}
s.auditFromRequest(r, "repo_item_sha_override", auditDetail("repo", repoFull, "number", strconv.Itoa(number), "labels", strings.Join(removed, ",")), "")
}
jsonResponse(w, repoHoldResponse{
OK: true, Repo: repoFull, Number: number, Removed: removed,
Result: repoHoldResult(repoFull, number, rowActionTargetIssue, false, shaLabel, removed),
})
}
24 changes: 24 additions & 0 deletions src/pkg/dashboard/api_repo_hold_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,30 @@ func TestRepoItemHoldToggleAuthorizationAndLabels(t *testing.T) {
}
}

func TestRepoItemSHAOverrideRequiresWriteAndPreservesOtherHolds(t *testing.T) {
mock := &repoHoldMock{permission: map[string]string{"writer": "maintain"}, issueLabels: []string{"needs-sha", "hold"}}
srv := newRepoHoldServer(t, mock)
post := func(user string) *httptest.ResponseRecorder {
req := httptest.NewRequest(http.MethodPost, "/api/repos/testorg/testrepo/items/7/hold", strings.NewReader(`{"held":false,"type":"issue","override_sha":true}`))
req.Header.Set("X-Hive-User", user)
w := httptest.NewRecorder()
srv.mux.ServeHTTP(w, req)
return w
}
if w := post("reader"); w.Code != http.StatusForbidden {
t.Fatalf("reader: %d %s", w.Code, w.Body.String())
}
if len(mock.added) != 0 || len(mock.removed) != 0 {
t.Fatal("reader changed labels")
}
if w := post("writer"); w.Code != http.StatusOK {
t.Fatalf("writer: %d %s", w.Code, w.Body.String())
}
if strings.Join(mock.added, ",") != github.SHAHoldOverrideLabel || strings.Join(mock.removed, ",") != "needs-sha" {
t.Fatalf("added %v, removed %v; want override and needs-sha only", mock.added, mock.removed)
}
}

// TestRepoItemHoldGitHubFailureIsNotAGatewayStatus: a hold on an issue whose
// GitHub label write fails answers 424 with GitHub's reason — never 502/503,
// which the hosted Ingress replaces with its generic "hive unavailable" page
Expand Down
8 changes: 5 additions & 3 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -366,9 +366,11 @@ type StageTrackerItem struct {
OpenChildren int `json:"open_children,omitempty"`
// Labels are the item's GitHub labels as the snapshot saw them, so the
// dashboard can offer a label filter without a second endpoint.
Labels []string `json:"labels,omitempty"`
CreatedAt *time.Time `json:"created_at,omitempty"`
UpdatedAt *time.Time `json:"updated_at,omitempty"`
Labels []string `json:"labels,omitempty"`
// SHA hold label actually present on this issue, including configured names.
SHAHoldLabel string `json:"sha_hold_label,omitempty"`
CreatedAt *time.Time `json:"created_at,omitempty"`
UpdatedAt *time.Time `json:"updated_at,omitempty"`
// Bucket is the enumeration bucket of an item outside the actionable
// set (claimed, in_progress, claimed_by_pr, filtered, hive_advisory,
// reporter_triage, draft, …) and BucketReason the enumeration's note;
Expand Down
13 changes: 13 additions & 0 deletions src/pkg/dashboard/stage_tracker_build.go
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,19 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
Labels: append([]string(nil), issue.Labels...), CreatedAt: timePtr(issue.CreatedAt), UpdatedAt: timePtr(issue.UpdatedAt),
Bucket: bucket, BucketReason: bucketReason,
URL: overviewItemURL(issue.URL, issue.Repo, issue.Number, "issue", status.GitHubBaseURL)}
shaLabel := config.DefaultSHAHoldTrustedLabel
if cfg != nil {
shaLabel = cfg.Issues.EffectiveSHAHoldTrustedLabel()
}
if strings.EqualFold(strings.TrimSpace(shaLabel), "hold") {
shaLabel = config.DefaultSHAHoldTrustedLabel
}
for _, label := range issue.Labels {
if strings.EqualFold(strings.TrimSpace(label), config.DefaultSHAHoldTrustedLabel) || strings.EqualFold(strings.TrimSpace(label), shaLabel) {
it.SHAHoldLabel = label
break
}
}
it.Children = issue.Children
if it.Children == nil {
it.Children = progress
Expand Down
Loading
Loading