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-needs-sha-gate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `needs-sha` now keeps the hive off an issue until the reporter adds a commit SHA, whatever the reporter-trust setting: an issue wearing it (the configured `issues.sha_hold_trusted_label`, default `needs-sha`) leaves every agent work lane, so nothing implements, decomposes or claims it. The SHA-hold sweep removes the label once a SHA appears, which releases the issue. This restores the safety the old `hold` gave after #18542 stopped the hive applying `hold`. The label is created with the description "Waiting on the reporter for the commit SHA; hive won't work this until it's added."
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` (#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 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`).
- 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`; an untrusted reporter's issue stays out of automatic work through the reporter-trust gate. 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 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).

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

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

#### `needs-sha` from SHA-hold

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

Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same `<!-- hive:sha-hold -->` notice instead of `hold`; the issue stays actionable. The sweep removes it once a SHA appears.
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."

**Who applies it:** Hive.

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 notice is the same; the issue stays actionable. 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`. | 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.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:5286-5296`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5336-5346`, 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
50 changes: 50 additions & 0 deletions src/pkg/github/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,9 @@ type Client struct {
issueFilter IssueAdmitter
agentIssueDecisionPolicyMu sync.RWMutex
agentIssueDecisionPolicy string
// needsSHALabelName is the configured SHA-hold label, recorded by each
// EnforceSHAHold sweep (guarded by issueFilterMu). Empty means the default.
needsSHALabelName string
// reporterConfirmationEnabled restores the legacy close gate for all
// human-filed bug-family issues when configured. Nil/false means only
// per-issue opt-in markers activate the gate.
Expand Down Expand Up @@ -1975,6 +1978,13 @@ func (c *Client) fetchIssues(ctx context.Context, repo string, now time.Time, re
details = append(details, c.workIssue(repo, issue, labels, "filtered", issueNeedsReporterConfirmationLabel))
continue
}
// needs-sha: waiting on the reporter for a commit SHA. Out of every
// agent lane whatever the reporter-trust setting (hivecommons/hive#18542).
if label := c.needsSHALabelOn(labels); label != "" {
breakdown.Filtered++
details = append(details, c.workIssue(repo, issue, labels, "filtered", label))
continue
}
if suppress := hardSuppressIssueBucket(issueFilter, labels); suppress != "" {
breakdown.Filtered++
breakdown.addHardSuppress(suppress)
Expand Down Expand Up @@ -4692,6 +4702,43 @@ type SHAHoldResult struct {
// configured (config.DefaultSHAHoldTrustedLabel).
const defaultSHAHoldLabel = "needs-sha"

// NeedsSHALabelDescription is the repo label description for the SHA-hold label.
const NeedsSHALabelDescription = "Waiting on the reporter for the commit SHA; hive won't work this until it's added."

// needsSHALabelOn returns the SHA-hold label the labels carry (the configured
// name, or the default name), or "" when none. An issue wearing it is parked
// on the reporter and kept out of agent work lanes.
func (c *Client) needsSHALabelOn(labels []string) string {
c.issueFilterMu.RLock()
configured := c.needsSHALabelName
c.issueFilterMu.RUnlock()
for _, name := range []string{configured, defaultSHAHoldLabel} {
if name = strings.TrimSpace(name); name == "" {
continue
}
for _, l := range labels {
if strings.EqualFold(strings.TrimSpace(l), name) {
return name
}
}
}
return ""
}

func (c *Client) setNeedsSHALabel(name string) {
c.issueFilterMu.Lock()
c.needsSHALabelName = strings.TrimSpace(name)
c.issueFilterMu.Unlock()
}

// ensureNeedsSHALabel creates the SHA-hold label with its description when
// the repo lacks it. Best effort: the label add that follows still works.
func (c *Client) ensureNeedsSHALabel(ctx context.Context, owner, repo, name string) {
if err := c.EnsureIssueLabel(ctx, owner+"/"+repo, name, "fbca04", NeedsSHALabelDescription); err != nil {
c.logger.Warn("could not ensure SHA-hold label", "repo", repo, "label", name, "error", err)
}
}

// shaHoldLabel returns the label the sweep applies to an issue missing a SHA.
// It is never `hold`: a `hold` means a person said hands-off, and the hive
// no longer applies one itself (hivecommons/hive#18468). Before #18468 an
Expand All @@ -4714,6 +4761,7 @@ func (c *Client) EnforceSHAHold(ctx context.Context, cfg SHAHoldConfig) (*SHAHol
}
result := &SHAHoldResult{}
owner, repo := c.splitRepo(cfg.PrimaryRepo)
c.setNeedsSHALabel(cfg.shaHoldLabel())

opts := &gh.IssueListByRepoOptions{
State: "open",
Expand Down Expand Up @@ -4771,6 +4819,7 @@ func (c *Client) enforceSoftSHAHold(ctx context.Context, owner, repo string, num
return
}
if !hasSHA && !softHeld {
c.ensureNeedsSHALabel(ctx, owner, repo, soft)
if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{soft}); err != nil {
c.logger.Warn("failed to add soft SHA label", "repo", repo, "issue", number, "label", soft, "error", err)
result.Skipped++
Expand All @@ -4797,6 +4846,7 @@ func (c *Client) enforceSoftSHAHold(ctx context.Context, owner, repo string, num
result.Unheld++
c.logger.Info("SHA-UNHOLD", "repo", repo, "issue", number, "author", author, "label", soft)
case !hasSHA && !softHeld:
c.ensureNeedsSHALabel(ctx, owner, repo, soft)
if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{soft}); err != nil {
c.logger.Warn("failed to add soft SHA label", "repo", repo, "issue", number, "label", soft, "error", err)
result.Skipped++
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/github/labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,10 @@ var escalationIssueLabelDefinitions = map[string]issueLabelDefinition{
color: "fbca04",
description: "Hive is waiting for the issue reporter or a maintainer to confirm the fix",
},
defaultSHAHoldLabel: {
color: "fbca04",
description: NeedsSHALabelDescription,
},
issueNeedsSpecLabel: {
color: "bfd4f2",
description: "Hive needs a specification or acceptance criteria before continuing",
Expand Down
92 changes: 92 additions & 0 deletions src/pkg/github/needs_sha_gate_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
package github

import (
"context"
"net/http"
"net/http/httptest"
"testing"
"time"

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

func needsSHAIssues() []wireIssue {
return []wireIssue{
{Number: 1, Title: "bug without sha", User: wireUser{"maintainer"}, AuthorAssociation: "MEMBER",
Labels: []wireLabel{{Name: "kind/bug"}, {Name: "needs-sha"}}, CreatedAt: hoursAgo(3)},
{Number: 2, Title: "bug with sha supplied", User: wireUser{"maintainer"}, AuthorAssociation: "MEMBER",
Labels: []wireLabel{{Name: "kind/bug"}}, CreatedAt: hoursAgo(2)},
}
}

func enumerateNeedsSHA(t *testing.T, f config.IssueFilterConfig, label string) *ActionableResult {
t.Helper()
org, repo := "testorg", "testrepo"
server := httptest.NewServer(buildMux(t, org, repo, needsSHAIssues(), nil))
t.Cleanup(server.Close)
c := newTestClient(t, server, org, []string{repo})
c.SetIssueFilter(f)
if label != "" {
c.setNeedsSHALabel(label)
}
result, err := c.EnumerateActionable(context.Background())
if err != nil {
t.Fatalf("EnumerateActionable: %v", err)
}
return result
}

// A needs-sha issue is never dispatched, with reporter trust on or off; the
// issue whose label was removed (a SHA arrived) is workable.
func TestEnumerateActionable_NeedsSHAKeepsIssueOutOfWork(t *testing.T) {
cases := map[string]config.IssueFilterConfig{
"reporter trust off": {},
"reporter trust on": enabledReporterTrust(),
}
for name, f := range cases {
t.Run(name, func(t *testing.T) {
nums := actionableNumbers(enumerateNeedsSHA(t, f, ""))
if nums[1] {
t.Error("needs-sha issue entered the actionable set")
}
if !nums[2] {
t.Error("positive control failed: the issue without needs-sha must be actionable")
}
})
}
}

func TestEnumerateActionable_NeedsSHAConfiguredName(t *testing.T) {
org, repo := "testorg", "testrepo"
issues := needsSHAIssues()
issues[0].Labels = []wireLabel{{Name: "kind/bug"}, {Name: "awaiting-sha"}}
server := httptest.NewServer(buildMux(t, org, repo, issues, nil))
t.Cleanup(server.Close)
c := newTestClient(t, server, org, []string{repo})
c.setNeedsSHALabel("awaiting-sha")
result, err := c.EnumerateActionable(context.Background())
if err != nil {
t.Fatalf("EnumerateActionable: %v", err)
}
if actionableNumbers(result)[1] {
t.Error("issue wearing the configured SHA label entered the actionable set")
}
}

func TestClassifyWebhookIssue_NeedsSHASidelined(t *testing.T) {
c := newTestClient(t, httptest.NewServer(http.NotFoundHandler()), "o", []string{"r"})
for name, f := range map[string]config.IssueFilterConfig{"off": {}, "on": enabledReporterTrust()} {
t.Run(name, func(t *testing.T) {
c.SetIssueFilter(f)
issue := &gh.Issue{Number: gh.Ptr(7), State: gh.Ptr("open"), Title: gh.Ptr("bug"),
User: &gh.User{Login: gh.Ptr("maintainer")}, AuthorAssociation: gh.Ptr("MEMBER"),
Labels: []*gh.Label{{Name: gh.Ptr("kind/bug")}, {Name: gh.Ptr("needs-sha")}},
CreatedAt: &gh.Timestamp{Time: time.Now().Add(-time.Hour)}}
p := c.classifyWebhookIssue("o/r", issue, issueLabelNames(issue.Labels), time.Now())
if p.Bucket != WebhookBucketSidelined || p.WorkIssue == nil || p.WorkIssue.Reason != "needs-sha" {
t.Fatalf("patch = %+v, want sidelined with reason needs-sha", p)
}
})
}
}
3 changes: 3 additions & 0 deletions src/pkg/github/webhook_item_patch.go
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,9 @@ func (c *Client) classifyWebhookIssue(repo string, issue *gh.Issue, labels []str
if labelPresent(labels, issueNeedsReporterConfirmationLabel) {
return sidelined("filtered", issueNeedsReporterConfirmationLabel)
}
if label := c.needsSHALabelOn(labels); label != "" {
return sidelined("filtered", label)
}
if suppress := hardSuppressIssueBucket(issueFilter, labels); suppress != "" {
return sidelined("filtered", suppress)
}
Expand Down
Loading