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-human-merge-sweep.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Enforce the `auto_merge.human_merge_pin_only` exception in the automerge sweep lanes and `/hive approve` (#16266): a PR by a listed trusted author whose complete diff is pin replacements on guarded paths is no longer held for a person. Any other changed file, including an unguarded changelog or doc, keeps the hold (#16326). Repos without an enabled entry are unchanged, and the `hive-merge` relay does not apply the exception yet (#16265).
1 change: 1 addition & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -2194,6 +2194,7 @@ func (b *boot) bootAgentsWith(deps bootAgentsDeps) {
// Human-merge paths (#11038): read through b.cfg on every evaluation so
// a reload of auto_merge.human_merge_paths applies without a restart.
autoMergeOpts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(b.cfg, repo) }
autoMergeOpts.HumanMergePinOnly = func(repo string) (config.PinOnlyException, bool) { return humanMergePinOnlyFor(b.cfg, repo) }
autoMergeOpts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(b.cfg) }
autoMergeOpts.RequireCurrentBase = func(repo string) bool { return b.cfg != nil && b.cfg.AutoMerge.RequireCurrentBaseFor(repo) }
autoMergeOpts.RequireCurrentBaseStrict = func(repo string) bool {
Expand Down
10 changes: 10 additions & 0 deletions src/cmd/hive/main_helpers.go
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,16 @@ func humanMergePathsFor(cfg *config.Config, repo string) []string {
return cfg.AutoMerge.HumanMergePathsFor(repo)
}

// humanMergePinOnlyFor returns the enabled auto_merge.human_merge_pin_only
// exception for repo (owner/repo), read through cfg on every evaluation so a
// reload applies without a restart (#16266). nil cfg means no exception.
func humanMergePinOnlyFor(cfg *config.Config, repo string) (config.PinOnlyException, bool) {
if cfg == nil {
return config.PinOnlyException{}, false
}
return cfg.AutoMerge.HumanMergePinOnlyFor(repo)
}

// humanMergeRuleFor reads auto_merge.human_merge_title_prefixes /
// human_merge_labels through cfg on every call so a reload applies
// (hivecommons/hive#15442). A nil config means the defaults.
Expand Down
2 changes: 2 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -846,6 +846,7 @@ func runAutoMergeSweepIfDue(ctx context.Context, ghClient *github.Client, cfg *c
opts.RepoAutoMergeEnabled = func(repo string) bool { return cfg.RepoAutoMergeEnabled(repo) }
opts.RepoOnGitHub = func(repo string) bool { return cfg.RepoOnGitHub(repo) }
opts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(cfg, repo) }
opts.HumanMergePinOnly = func(repo string) (config.PinOnlyException, bool) { return humanMergePinOnlyFor(cfg, repo) }
opts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(cfg) }
opts.RequireCurrentBase = func(repo string) bool { return cfg.AutoMerge.RequireCurrentBaseFor(repo) }
opts.RequireCurrentBaseStrict = func(repo string) bool { return cfg.AutoMerge.RequireCurrentBaseStrictFor(repo) }
Expand Down Expand Up @@ -1443,6 +1444,7 @@ func runIssueUnparkSweepIfDue(ctx context.Context, ghClient *github.Client, cfg
if cfg != nil {
approveOpts.RepoAutoMergeEnabled = cfg.RepoAutoMergeEnabled
approveOpts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(cfg, repo) }
approveOpts.HumanMergePinOnly = func(repo string) (config.PinOnlyException, bool) { return humanMergePinOnlyFor(cfg, repo) }
approveOpts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(cfg) }
approveOpts.TrustedBotAuthors = func() map[string]bool { return cfg.AutoMerge.TrustedBotAuthorSet() }
}
Expand Down
39 changes: 28 additions & 11 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,12 +170,23 @@ 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).

**Staged pin-only policy (not yet enforced).**
**Pin-only policy (enforced by the automerge sweep and `/approve`; relay pending).**

`auto_merge.human_merge_pin_only` provides the schema and conservative diff
classifier for #16242 / #16262. **It does not currently enable an exception:**
relay, sweep, `/approve` and native-queue gates still require the existing
human-merge path policy. Do not remove `human_merge_paths` or manually clear a
classifier for #16242 / #16262. **The automerge sweep lanes and `/approve`
enforce it (#16266); the `hive-merge` relay does not yet** (#16265) and still
requires the existing human-merge path policy. The native merge queue is entered
only after a lane's human-merge-path gate, so queued PRs inherit the exception. A sweep lane
does not hold a PR on its human-merge-path matches when the repo has an enabled
entry, the PR author is in `trusted_authors` (case-insensitive login match),
GitHub's reported changed-file count is present and equals the fetched list,
and the classifier accepts the diff. The check reuses the file list the path
gate already fetches, so it costs no extra API call; a repo without an enabled
entry behaves exactly as before. `/hive approve` applies the same check, so its
reply never contradicts the lane. Any other outcome holds the PR as before.
The exception only prevents a new path hold: a PR that already carries `hold`
stays held until a person (or the #16269 release integration) clears it.
Do not remove `human_merge_paths` or manually clear a
hold to simulate this feature. The YAML example, per-field contract and seed
reload instructions live in the
[operator reference](operator-reference/README.md#human-merge-pin-only-rollout);
Expand All @@ -185,7 +196,11 @@ Repository keys are case-insensitive; duplicate normalized keys are rejected.
Absent/disabled entries have no effect. Enabled entries require nonempty paths,
kinds and trusted authors; unknown kinds are rejected, including when disabled.
The classifier accepts only existing modified files in both the actual guarded
path matches and exception paths, and checks **all** files in the PR. Every
path matches and exception paths, and checks **all** files in the PR: callers
pass the full changed-file list, so a pin bump that also edits any unguarded
file — including a changelog fragment or documentation — is not pin-only and
stays held for a person (#16326). Bump tooling that adds such files must open
them in a separate PR. Every
changed line must be a paired pin replacement. Supported forms are unquoted
`uses: owner/repo[/path]@<40-hex>` (an existing simple `# vN[.N[.N]]`
comment may change), `FROM image@sha256:<64-hex>` / `image: image@sha256:...`,
Expand All @@ -195,16 +210,18 @@ permission/credential/signing text and non-pin edits fail closed.

This classifier proves **syntax only**, not authenticated identity, exact-head
binding, file-list completeness, semantic interpretation or review of upstream
references. Those proofs must be added by the integration children (#16265,
#16266); attribution and safe hold release are tracked in #16269. None of the
references. The sweep supplies the author (GitHub's PR author login) and
file-list completeness itself; the relay integration remains #16265;
attribution and safe hold release are tracked in #16269. None of the
schema or classifier APIs grants permission to merge or clears a hold. Native
required checks and producer bindings, freshness, current reviews, substantive
objections, unrelated holds and configured soak must remain independent gates.

Operators stage the key in the controller's configured `hive.yaml` seed, not in
the image repository (reload behaviour is documented in the operator reference
linked above). Reloading this schema alone still does **not** enable admission.
The integration PRs must wire live policy updates into every merge path.
linked above). On an image that contains #16266, reloading the seed enables
the sweep and `/approve` exception at once; the `hive-merge` relay still
ignores the key until #16265 lands, so relay merges keep holding matching PRs.

There is **no minimum deployable version enabling this lane yet**. Utah rollout
and current-head positive/negative deployment evidence remain tracked by
Expand All @@ -214,8 +231,8 @@ projectbluefin/utah#1082 and #16242; projectbluefin/utah#1068 is not pre-authori
`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.
(#16262), relay admission (#16265), and sweep admission (#16266, landed) 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
Expand Down
10 changes: 6 additions & 4 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through
| `project.label_driven_supersede_park_actors` | `[]` (off) | Automation logins (for example a lifecycle bot running as `github-actions[bot]`) whose park labels a later trusted acceptance supersedes on label-driven repos: Hive removes the label, says so in the release comment, and releases the issue ([#13605](https://github.com/hivecommons/hive/issues/13605)). Park labels added by people, by unlisted bots, or by a listed bot after the acceptance still block; `hold` is never superseded. Per-repo override: `project.repo_policies[].label_driven_supersede_park_actors`. |
| `auto_merge.allow_unprotected_base` | Deprecated no-op. | Accepted so older configs keep loading. `hive-merge` now merges into any protected or unprotected branch the App can write, subject to the CI-evidence gate and GitHub's own merge rules. |
| `auto_merge.no_ci_ok` | Empty by default. | Explicit repo list whose zero-CI merge-request verdict may pass; failing or pending CI evidence is still enforced. |
| `auto_merge.human_merge_pin_only` | Unset (off); **not yet enforced**. | Staged per-repo schema for `enabled`, `paths`, `kinds` (`action-sha`, `image-digest`, `version-pin`) and `trusted_authors`. Enabled entries require all three lists. Provides syntax-classification building blocks only: no merge route grants an exception or clears a hold. See [hive-merge.md](../hive-merge.md) for grammar, restrictions and outstanding integration/deployment requirements (#16242). |
| `auto_merge.human_merge_pin_only` | Unset (off); enforced by the automerge sweep lanes and `/approve` (#16266), **not yet by the `hive-merge` relay** (#16265). | Per-repo schema for `enabled`, `paths`, `kinds` (`action-sha`, `image-digest`, `version-pin`) and `trusted_authors`. Enabled entries require all three lists. The sweep does not place a human-merge-path hold on a PR whose author is in `trusted_authors` and whose complete diff (every changed file, guarded or not) is pin replacements; it never clears an existing hold. See [hive-merge.md](../hive-merge.md) for grammar, restrictions and outstanding integration/deployment requirements (#16242). |
| `auto_merge.human_merge_paths` | Unset (off). | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge. Applies to every merge lane (App self-merge, trusted-author, label-queued, merge-request relay) whatever the intent tier; a matching PR is held with one comment, and an incomplete changed-file list fails closed. Details in the sweep key table below. |
| `auto_merge.human_merge_title_prefixes` | `["⚠️", "⚠"]` | Title prefixes (after trimming) that mark a PR as a breaking change a person must merge. Every auto-merge lane and the merge train skip the PR; the tracker parks it at 090 *Ready for human merge · human merge*. Set to `[]` to disable. |
| `auto_merge.human_merge_labels` | `["needs-owner-merge"]` | Labels (case-insensitive) that mark a PR a person must merge; same effect as the title prefixes. Set to `[]` to disable. |
Expand Down Expand Up @@ -456,7 +456,7 @@ advanced into the merge path.
| `auto_merge.repos.<repo>.required_checks` | inherits default | Per-repo override for heterogeneous hives. `<repo>` may be the bare name from `project.repos` or `owner/repo`; an explicit empty list declares that GitHub has no required contexts, while Hive still requires positive CI evidence from at least one real successful check-run before merge. |
| `auto_merge.allow_unprotected_base` | deprecated no-op | Accepted for compatibility only. [`hive-merge`](../hive-merge.md) no longer refuses solely because a base branch has no GitHub branch protection; it may merge into any branch the App can write after positive CI evidence. |
| `auto_merge.no_ci_ok` | unset (refuse) | **Merge-request watcher key, not a sweep key.** Per-repo opt-in that downgrades only the "unverified" CI verdict (zero statuses, check runs, and workflow runs) to green, for adopted repos with no CI by design. Red and pending verdicts are never downgraded (#6281). See [hive-merge.md](../hive-merge.md). |
| `auto_merge.human_merge_paths` | unset | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge, e.g. `Danathar/goodreads-mcp: [".claude/settings.json", ".claude/hooks/**"]`. Every App merge path honors it: the automerge sweep lanes (App self-merge, trusted-author, label-queued) and the agent merge-request relay refuse a PR that touches a listed path, add `hold`, and post one `<!-- hive-human-merge-path -->` comment naming the path(s); a person must merge it. If the changed-file list cannot be fetched completely for a configured repo, the merge is withheld (#11038, #11039). |
| `auto_merge.human_merge_paths` | unset | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge, e.g. `Danathar/goodreads-mcp: [".claude/settings.json", ".claude/hooks/**"]`. Every App merge path honors it: the automerge sweep lanes (App self-merge, trusted-author, label-queued) and the agent merge-request relay refuse a PR that touches a listed path, add `hold`, and post one `<!-- hive-human-merge-path -->` comment naming the path(s); a person must merge it. The sweep lanes skip that hold only for a PR admitted by `auto_merge.human_merge_pin_only` (#16266); the relay does not apply that exception yet. If the changed-file list cannot be fetched completely for a configured repo, the merge is withheld (#11038, #11039). |
| `auto_merge.human_merge_title_prefixes` | `["⚠️", "⚠"]` | PR-title prefixes that mean "breaking change — owner merges" (U+26A0 with or without the VS16 selector by default, matched after trimming leading whitespace). One shared predicate, `automerge.RequiresHumanMerge(pr)`, runs where each lane computes eligibility — App self-merge, label-queued, trusted-author and contributor lanes, plus the refetch before a merge — so a matching PR is never merged by hive and never fronts a merge train, however green and however approved. The PR parks at stage 090 *Ready for human merge* with the `human merge` chip and reason *breaking change — owner merges*; the owner merges it with **Approve & merge as maintainer** or on GitHub. Hive posts one writeback-gated comment saying it will wait for a human. Set to `[]` to turn the title rule off. Added after a ⚠️-titled PR was auto-merged by the trusted-author lane while its owner was still deciding whether to ship it. |
| `auto_merge.human_merge_labels` | `["needs-owner-merge"]` | Labels (case-insensitive, trimmed) that carry the same "a person merges this" meaning as the title prefixes above; either match is enough. Set to `[]` to turn the label rule off. |
| `auto_merge.require_current_base` | unset | Repo list (`owner/repo`) with an explicit **on** override for the current-base merge gate (Settings → Repos → "Merge only on current base"). On a gated repo the App self-merge, trusted-author and contributor lanes only merge a head that contains the current base tip. A green head tested against an older base is updated with GitHub update-branch (a merge commit; no author commit is rewritten) and merges once CI is green on the new head, so a semantic conflict with work merged since turns that PR red instead of breaking the base ([#13634](https://github.com/hivecommons/hive/issues/13634), [#15335](https://github.com/hivecommons/hive/issues/15335)). Costs one compare call per merge candidate. Listing a repo here is also **strict**: a behind head the App cannot update (fork without maintainer edits, branch protection or a missing `contents: write`) is parked (`fork-not-editable` / `update-branch`) rather than merged as tested. Wins over `skip_current_base` and over the default. |
Expand Down Expand Up @@ -497,15 +497,17 @@ hosted spoke changes survive restarts without editing `hive.yaml`.

### Human-merge pin-only rollout

**Availability:** not yet enforced by this attribution change alone. Minimum
**Availability:** the automerge sweep lanes and `/approve` enforce the
exception (#16266); the relay does not yet. 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 additive configuration (schema landed in #16262; not yet enforced) is:
The additive configuration (schema #16262; enforced by the automerge sweep lanes
and `/approve` per #16266, relay pending #16265) is:

```yaml
auto_merge:
Expand Down
8 changes: 5 additions & 3 deletions src/pkg/config/automerge_pin_only.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@ import (
"github.com/hivecommons/hive/pkg/intent"
)

// PinOnlyException is staged policy, not authorization to merge. The eventual
// admission gates must supply authenticated identity, exact-head diff and review
// evidence before consulting the purely syntactic classifier.
// PinOnlyException is policy wired in Engine.SetHumanMergePinOnly and
// enforced by the automerge sweep and /approve gates via humanMergePinOnlyExempt
// (#16266). It proves trusted PR author, complete file list, and SHA-bound merge,
// but not upstream review (separate gates handle that). The hive-merge relay does
// not yet apply it (#16265).
type PinOnlyException struct {
Enabled bool `yaml:"enabled" json:"enabled"`
Paths []string `yaml:"paths" json:"paths"`
Expand Down
5 changes: 3 additions & 2 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -8340,8 +8340,9 @@ type AutoMergeConfig struct {
// lives in the merge sweeps.
HumanMergePaths map[string][]string `yaml:"human_merge_paths,omitempty" json:"human_merge_paths,omitempty"`

// HumanMergePinOnly stages opt-in pin-only policy. Admission wiring must
// independently prove trusted identity, exact-head evidence and upstream review.
// HumanMergePinOnly holds the opt-in pin-only exception, enforced by the
// automerge sweep and /approve gates via humanMergePinOnlyExempt (#16266);
// the hive-merge relay does not apply it yet (#16265).
HumanMergePinOnly map[string]PinOnlyException `yaml:"human_merge_pin_only,omitempty" json:"human_merge_pin_only,omitempty"`
// HumanMergeTitlePrefixes lists title prefixes (matched after trimming
// the title) that mark a PR as one the owner merges by hand; no lane and
Expand Down
Loading
Loading