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/added-pin-only-hold-attribution.md
Original file line number Diff line number Diff line change
@@ -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).
23 changes: 23 additions & 0 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<!-- hive-human-merge-path -->` and append
`<!-- hive-human-merge-path-head: <40-character SHA> -->` 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`
Expand Down
57 changes: 57 additions & 0 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/github/automerge/automerge_human_paths.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
163 changes: 163 additions & 0 deletions src/pkg/github/human_merge_path_release.go
Original file line number Diff line number Diff line change
@@ -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 "<!-- hive-human-merge-path-head: " + head + " -->"
}

// 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 = "<!-- hive-human-merge-path-head: "
start := strings.Index(body, prefix)
if start < 0 {
return false, nil
}
tail := strings.TrimPrefix(body[start:], prefix)
if len(tail) < 44 || !validHumanMergeHead(tail[:40]) || !strings.HasPrefix(tail[40:], " -->") {
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
}
Loading
Loading