diff --git a/changelog.d/added-pin-only-hold-attribution.md b/changelog.d/added-pin-only-hold-attribution.md new file mode 100644 index 0000000000..3c959c6143 --- /dev/null +++ b/changelog.d/added-pin-only-hold-attribution.md @@ -0,0 +1 @@ +- Human-merge-path holds now record their exact head without claiming pre-existing holds; a shared fail-closed release API validates App ownership and complete label history for later pin-only admission integration, with operator rollout prerequisites documented (#16269). diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index fa451fc8ba..4917c79866 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -154,6 +154,29 @@ sweep lanes whatever the intent tier. If the changed-file list for a configured repo cannot be fetched completely, the merge is withheld (fail closed). See [operator-reference.md](operator-reference.md). +**Pin-only exception rollout (#16242).** The proposed opt-in key is +`auto_merge.human_merge_pin_only`; see the +[operator reference](operator-reference/README.md#human-merge-pin-only-rollout) +for its configuration and deployment prerequisites. The schema/classifier +(#16262), relay admission (#16265), and sweep admission (#16266) are separate +changes: this attribution change alone does **not** enable the exception. +New path-hold comments retain `` and append +`` only when Hive +observes that exact head without a pre-existing hold. Legacy comments and +pre-existing holds are not retroactively attributed. + +The shared release API requires a later, qualifying exact head, the configured +App identity, an unedited App marker, and complete label-event history proving +one App-applied path hold immediately before the notice. Human-applied or +re-added holds, ambiguous history, and timeline errors keep the hold. Admission +callers must supply their live writeback gate (a missing gate or denied +hold-gate notice leaves the hold intact), wire that API after pin-only +qualification, and re-read labels; +that wiring remains part of the rollout, not an authorization to clear labels +manually. Required checks and their producer bindings, strict freshness, +current reviews and substantive objections, other holds, and configured soak +remain mandatory. Neither a pin-looking diff nor this API authorizes a merge. + **Contributor PRs are held to the contributor-lane policy.** A merge request for a PR whose author is not the hive App, a configured trusted bot, or a trusted-author role is evaluated against the same `auto_merge.contributor_lane` diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 97abd1aa21..609d957291 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -494,6 +494,63 @@ 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`. +### Human-merge pin-only rollout + +**Availability:** not yet enforced by this attribution change alone. Minimum +supported version: the first deployed v5 release containing the schema/classifier +(#16262), relay (#16265), sweep (#16266), and hold-release admission integration +(#16269). No released version is established here; do not assume an existing +`candidate`, `latest`, or `stable` tag contains all four. Record the actual image +digest/version and live positive/negative evidence in projectbluefin/utah#1082 +before enabling that rollout. + +The planned additive configuration (requires the schema change) is: + +```yaml +auto_merge: + human_merge_paths: + projectbluefin/utah: [".github/workflows/**", "Containerfile"] + human_merge_pin_only: + projectbluefin/utah: + enabled: true + paths: [".github/workflows/*.yml", "Containerfile"] + kinds: [action-sha, image-digest, version-pin] + trusted_authors: [approved-maintenance-login] # replace with approved identities +``` + +| Field | Default / contract | +| --- | --- | +| Repository key | Case-insensitive `owner/repo`; configure each consumer separately. | +| `enabled` | Absent/false preserves the existing human-merge-path gate. | +| `paths` | Explicit allowed paths within the protected path matches, not a replacement for `human_merge_paths`. Required when enabled. | +| `kinds` | Explicit subset of `action-sha`, `image-digest`, `version-pin`; unknown kinds rejected. Required when enabled. | +| `trusted_authors` | Explicit authenticated author allowlist; required when enabled. Not permission to trust arbitrary bot-looking logins. | + +Edit the controller's active `hive.yaml` seed, not the consumer image repo. +The config file watcher loads the seed plus dashboard overlay after a debounced +file change and logs `config reloaded from file`; a rejected reload logs +`config reload failed` and does not install the change. See +[config layering](../config-layering.md) for seed/overlay precedence. Do not +assume the dashboard auto-merge editor exposes this new map. Verify both relay +and sweep lookups use the reloaded configuration before relying on it; use a +controller restart on the verified image if the running version lacks live wiring. + +Qualification requires a complete exact-head diff and trusted author, not just +SHA-shaped text. The exception never bypasses native required checks or producer +bindings, strict freshness, current review, substantive objections, unrelated +holds, or configured soak. Mixed logic/permissions/credential/trust-boundary +changes remain a person's merge. A candidate such as projectbluefin/utah#1068 +must qualify again on its then-current head. + +Path holds carry the legacy marker plus an exact-head attribution marker only +for newly applied holds. The shared release API fails closed on human-applied +or re-added holds, legacy/edited/ambiguous markers, or missing label timeline. +It only accepts one App-applied hold event immediately before the App notice; +older hold cycles are conservatively retained. Admission integration must call +it only after qualification, re-read labels, and keep all other gates. This is +not a manual hold-removal runbook or evidence that automatic release is already +wired in the running controller. + **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 diff --git a/src/pkg/github/automerge/automerge_human_paths.go b/src/pkg/github/automerge/automerge_human_paths.go index c8bf1a3d99..33bdc3c6e2 100644 --- a/src/pkg/github/automerge/automerge_human_paths.go +++ b/src/pkg/github/automerge/automerge_human_paths.go @@ -71,7 +71,7 @@ func (c *Engine) humanMergePathGate(ctx context.Context, displayRepo, owner, rep return "", nil } c.info("automerge sweep held PR touching human-merge paths", "repo", displayRepo, "pr", number, "paths", matches, "config", hgithub.HumanMergePathsConfigKey) - if err := hgithub.HoldForHumanMergePaths(ctx, c.gh, owner, repo, number, matches); err != nil { + if err := hgithub.HoldForHumanMergePaths(ctx, c.gh, owner, repo, number, matches, pr.GetHead().GetSHA()); err != nil { return autoMergeReasonHumanMergePath, err } return autoMergeReasonHumanMergePath, nil diff --git a/src/pkg/github/human_merge_path_release.go b/src/pkg/github/human_merge_path_release.go new file mode 100644 index 0000000000..dba660fcdd --- /dev/null +++ b/src/pkg/github/human_merge_path_release.go @@ -0,0 +1,163 @@ +package github + +import ( + "context" + "fmt" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/pkg/writeback" +) + +func validHumanMergeHead(head string) bool { + if len(head) != 40 { + return false + } + for _, c := range head { + if !strings.ContainsRune("0123456789abcdef", c) { + return false + } + } + return true +} + +func humanMergeHeadMarker(head string) string { + return "" +} + +// ReleaseHumanMergePathHold is shared by pin-only admission callers. qualified +// must mean the enabled policy qualified expectedHead using complete evidence, +// not merely that the diff contains SHA-shaped text. This only removes a label; +// it authorizes neither a merge nor bypassing any other merge gate. +// +// Ambiguous provenance (including legacy markers, edited comments, multiple hold +// applications, missing identity, or unavailable history) leaves the hold intact. +// Callers must supply the process writeback gate (nil fails closed), re-read +// labels after release, and retain exact-head merge binding. +func ReleaseHumanMergePathHold(ctx context.Context, client *gh.Client, gate *writeback.Gate, owner, repo string, number int, appLogin, expectedHead string, qualified bool) (bool, error) { + if !qualified || client == nil || gate == nil || strings.TrimSpace(appLogin) == "" || !validHumanMergeHead(expectedHead) { + return false, nil + } + pr, _, err := client.PullRequests.Get(ctx, owner, repo, number) + if err != nil { + return false, fmt.Errorf("fetching pin-only head: %w", err) + } + if pr.GetHead().GetSHA() != expectedHead { + return false, nil + } + held := false + for _, label := range pr.Labels { + held = held || strings.EqualFold(label.GetName(), HumanMergePathHoldLabel) + } + if !held { + return false, nil + } + + var notice *gh.IssueComment + opts := &gh.IssueListCommentsOptions{ListOptions: gh.ListOptions{PerPage: 100}} + for { + comments, resp, err := client.Issues.ListComments(ctx, owner, repo, number, opts) + if err != nil { + return false, fmt.Errorf("listing path hold comments: %w", err) + } + for _, comment := range comments { + if !strings.Contains(comment.GetBody(), HumanMergePathMarker) { + continue + } + // A second marker is ambiguous, even if authored by the App. + if notice != nil || !strings.EqualFold(comment.GetUser().GetLogin(), appLogin) || comment.GetUser().GetType() != "Bot" { + return false, nil + } + body := comment.GetBody() + const prefix = "") { + return false, nil + } + // Only stale path holds may be released, never the currently refused head. + if tail[:40] == expectedHead || comment.GetCreatedAt().IsZero() || !comment.GetUpdatedAt().Time.Equal(comment.GetCreatedAt().Time) { + return false, nil + } + notice = comment + } + if resp == nil { + return false, nil + } + if resp.NextPage == 0 { + break + } + opts.Page = resp.NextPage + } + if notice == nil { + return false, nil + } + + // Require exactly one hold transition in the complete history, owned by the + // configured App and immediately preceding its notice. Older remove/re-add + // cycles are deliberately not guessed at, even when the latest actor is App. + var applied *gh.IssueEvent + eventsOpts := &gh.ListOptions{PerPage: 100} + for { + events, resp, err := client.Issues.ListIssueEvents(ctx, owner, repo, number, eventsOpts) + if err != nil { + return false, fmt.Errorf("listing path hold timeline: %w", err) + } + for _, event := range events { + if !strings.EqualFold(event.GetLabel().GetName(), HumanMergePathHoldLabel) { + continue + } + if event.GetEvent() != "labeled" && event.GetEvent() != "unlabeled" { + continue + } + if applied != nil || event.GetEvent() != "labeled" || !strings.EqualFold(event.GetActor().GetLogin(), appLogin) || event.GetActor().GetType() != "Bot" { + return false, nil + } + delta := notice.GetCreatedAt().Sub(event.GetCreatedAt().Time) + if event.GetCreatedAt().IsZero() || delta < 0 || delta > time.Minute { + return false, nil + } + applied = event + } + if resp == nil { + return false, nil + } + if resp.NextPage == 0 { + break + } + eventsOpts.Page = resp.NextPage + } + if applied == nil { + return false, nil + } + // Refetch the head immediately before the write; GitHub label deletion has no + // conditional-write API, so this is not a substitute for the merge SHA guard. + current, _, err := client.PullRequests.Get(ctx, owner, repo, number) + if err != nil { + return false, err + } + if current.GetHead().GetSHA() != expectedHead { + return false, nil + } + item := writeback.Item{ + Number: number, + IsPR: true, + Author: current.GetUser().GetLogin(), + HiveAuthored: strings.EqualFold(current.GetUser().GetLogin(), appLogin) && current.GetUser().GetType() == "Bot", + CreatedAt: current.GetCreatedAt().Time, + } + for _, label := range current.Labels { + item.Labels = append(item.Labels, label.GetName()) + } + if !gate.Allowed(owner+"/"+repo, item, writeback.KindHoldGateNotice).Allowed { + return false, nil + } + if _, err := client.Issues.RemoveLabelForIssue(ctx, owner, repo, number, HumanMergePathHoldLabel); err != nil { // writeback:gated + return false, fmt.Errorf("releasing path hold: %w", err) + } + return true, nil +} diff --git a/src/pkg/github/human_merge_path_release_test.go b/src/pkg/github/human_merge_path_release_test.go new file mode 100644 index 0000000000..967b693dee --- /dev/null +++ b/src/pkg/github/human_merge_path_release_test.go @@ -0,0 +1,165 @@ +package github + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + + gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/pkg/writeback" +) + +func TestReleaseHumanMergePathHold(t *testing.T) { + oldHead := strings.Repeat("a", 40) + head := strings.Repeat("b", 40) + for _, tc := range []struct { + name string + actor string + extraEvent bool + timelineError bool + qualified bool + legacy bool + edited bool + changedHead bool + noGate bool + mode writeback.RepoMode + paused bool + want bool + }{ + {name: "App-only stale path hold", actor: "hive[bot]", qualified: true, want: true}, + {name: "missing writeback gate", actor: "hive[bot]", qualified: true, noGate: true}, + {name: "writeback off", actor: "hive[bot]", qualified: true, mode: writeback.RepoModeOff}, + {name: "writeback issues only", actor: "hive[bot]", qualified: true, mode: writeback.RepoModeIssuesOnly}, + {name: "writeback paused", actor: "hive[bot]", qualified: true, paused: true}, + {name: "human hold", actor: "person", qualified: true}, + {name: "human re-added hold", actor: "hive[bot]", extraEvent: true, qualified: true}, + {name: "non-qualifying head", actor: "hive[bot]"}, + {name: "unknown timeline", actor: "hive[bot]", timelineError: true, qualified: true}, + {name: "legacy marker", actor: "hive[bot]", legacy: true, qualified: true}, + {name: "edited marker", actor: "hive[bot]", edited: true, qualified: true}, + {name: "changed head", actor: "hive[bot]", changedHead: true, qualified: true}, + } { + t.Run(tc.name, func(t *testing.T) { + deletes, calls := 0, 0 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls++ + w.Header().Set("Content-Type", "application/json") + switch { + case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/pulls/1"): + currentHead := head + if tc.changedHead { + currentHead = oldHead + } + _ = json.NewEncoder(w).Encode(map[string]any{"head": map[string]string{"sha": currentHead}, "labels": []map[string]string{{"name": "hold"}}}) + case strings.HasSuffix(r.URL.Path, "/comments"): + body := HumanMergePathComment([]string{"Containerfile"}) + if !tc.legacy { + body += humanMergeHeadMarker(oldHead) + } + updated := "2026-11-02T12:00:02Z" + if tc.edited { + updated = "2026-11-02T12:00:03Z" + } + _ = json.NewEncoder(w).Encode([]map[string]any{{"body": body, "created_at": "2026-11-02T12:00:02Z", "updated_at": updated, "user": map[string]string{"login": "hive[bot]", "type": "Bot"}}}) + case strings.HasSuffix(r.URL.Path, "/events"): + if tc.timelineError { + w.WriteHeader(500) + return + } + events := []map[string]any{{"event": "labeled", "created_at": "2026-11-02T12:00:01Z", "label": map[string]string{"name": "hold"}, "actor": map[string]string{"login": tc.actor, "type": "Bot"}}} + if tc.extraEvent { + events = append(events, map[string]any{"event": "labeled", "created_at": "2026-11-02T12:00:03Z", "label": map[string]string{"name": "hold"}, "actor": map[string]string{"login": "person", "type": "User"}}) + } + _ = json.NewEncoder(w).Encode(events) + case r.Method == http.MethodDelete && strings.HasSuffix(r.URL.Path, "/labels/hold"): + deletes++ + w.WriteHeader(http.StatusNoContent) + default: + t.Errorf("unexpected request %s %s", r.Method, r.URL.Path) + w.WriteHeader(404) + } + })) + defer srv.Close() + client, err := gh.NewClient(srv.Client()).WithEnterpriseURLs(srv.URL, srv.URL) + if err != nil { + t.Fatal(err) + } + mode := tc.mode + if mode == writeback.RepoModeDefault { + mode = writeback.RepoModeFull + } + gate := writeback.New(writeback.Config{ + PerRepo: map[string]writeback.RepoOverride{"o/r": {Mode: mode}}, + }, writeback.Deps{ + RepoPause: func(string) (writeback.RepoPauseInfo, bool) { + return writeback.RepoPauseInfo{}, tc.paused + }, + }, "") + if tc.noGate { + gate = nil + } + released, err := ReleaseHumanMergePathHold(context.Background(), client, gate, "o", "r", 1, "hive[bot]", head, tc.qualified) + if released != tc.want || (deletes == 1) != tc.want { + t.Fatalf("released=%v deletes=%d err=%v", released, deletes, err) + } + if tc.want && err != nil { + t.Fatalf("successful release returned an error: %v", err) + } + if tc.timelineError && err == nil { + t.Fatal("timeline failure must be reported") + } + if (!tc.qualified || tc.noGate) && calls != 0 { + t.Fatalf("non-qualifying request made %d calls", calls) + } + }) + } +} + +func TestHumanMergeHoldHeadAttribution(t *testing.T) { + head := strings.Repeat("a", 40) + for _, existingHold := range []bool{false, true} { + t.Run(map[bool]string{false: "new hold", true: "existing unrelated hold"}[existingHold], func(t *testing.T) { + var posted string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch { + case strings.HasSuffix(r.URL.Path, "/pulls/1"): + labels := []map[string]string{} + if existingHold { + labels = append(labels, map[string]string{"name": "hold"}) + } + _ = json.NewEncoder(w).Encode(map[string]any{"head": map[string]string{"sha": head}, "labels": labels}) + case strings.HasSuffix(r.URL.Path, "/labels"): + _, _ = w.Write([]byte(`[{"name":"hold"}]`)) + case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/comments"): + _, _ = w.Write([]byte(`[]`)) + case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/comments"): + var comment gh.IssueComment + _ = json.NewDecoder(r.Body).Decode(&comment) + posted = comment.GetBody() + _, _ = w.Write([]byte(`{"id":1}`)) + default: + t.Errorf("unexpected request %s", r.URL.Path) + w.WriteHeader(404) + } + })) + defer srv.Close() + client, err := gh.NewClient(srv.Client()).WithEnterpriseURLs(srv.URL, srv.URL) + if err != nil { + t.Fatal(err) + } + if err := HoldForHumanMergePaths(context.Background(), client, "o", "r", 1, []string{"Containerfile"}, head); err != nil { + t.Fatal(err) + } + if !strings.Contains(posted, HumanMergePathMarker) { + t.Fatal("legacy marker must remain matchable") + } + if strings.Contains(posted, humanMergeHeadMarker(head)) == existingHold { + t.Fatalf("wrong attribution: %s", posted) + } + }) + } +} diff --git a/src/pkg/github/human_merge_paths.go b/src/pkg/github/human_merge_paths.go index 2d45f338bc..009554151e 100644 --- a/src/pkg/github/human_merge_paths.go +++ b/src/pkg/github/human_merge_paths.go @@ -96,10 +96,27 @@ func HumanMergePathComment(matches []string) string { // marker-stamped comment naming matches, unless a comment carrying // HumanMergePathMarker already exists. Shared by the sweep lanes and the // merge-request relay so both leave exactly one comment. -func HoldForHumanMergePaths(ctx context.Context, client *gh.Client, owner, repo string, number int, matches []string) error { +func HoldForHumanMergePaths(ctx context.Context, client *gh.Client, owner, repo string, number int, matches []string, head ...string) error { if client == nil { return fmt.Errorf("human-merge-path hold: no client") } + // Never attribute an existing hold to this policy. Older callers without an + // exact head retain the legacy, non-releasable marker. + attributedHead := "" + if len(head) == 1 && validHumanMergeHead(head[0]) { + pr, _, err := client.PullRequests.Get(ctx, owner, repo, number) + if err != nil { + return fmt.Errorf("fetching human-merge-path head: %w", err) + } + if pr.GetHead().GetSHA() == head[0] { + attributedHead = head[0] + for _, label := range pr.Labels { + if strings.EqualFold(label.GetName(), HumanMergePathHoldLabel) { + attributedHead = "" + } + } + } + } if _, _, err := client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{HumanMergePathHoldLabel}); err != nil { return fmt.Errorf("adding %s label: %w", HumanMergePathHoldLabel, err) } @@ -110,7 +127,11 @@ func HoldForHumanMergePaths(ctx context.Context, client *gh.Client, owner, repo if posted { return nil } - if _, _, err := client.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(HumanMergePathComment(matches))}); err != nil { + body := HumanMergePathComment(matches) + if attributedHead != "" { + body += humanMergeHeadMarker(attributedHead) + "\n" + } + if _, _, err := client.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { return fmt.Errorf("posting human-merge-path comment: %w", err) } return nil @@ -194,7 +215,7 @@ func (c *Client) mergeRequestHumanMergePathRefusal(ctx context.Context, req Merg if len(matches) == 0 { return "", nil } - if err := HoldForHumanMergePaths(ctx, c.client, owner, name, req.Number, matches); err != nil { + if err := HoldForHumanMergePaths(ctx, c.client, owner, name, req.Number, matches, pr.GetHead().GetSHA()); err != nil { c.warn("merge-request watcher: human-merge-path hold failed", "repo", req.Repo, "pr", req.Number, "error", err) } return HumanMergePathReason(matches), nil