Skip to content
Merged
1 change: 1 addition & 0 deletions changelog.d/added-human-merge-owner-approval.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- New opt-in setting `auto_merge.human_merge_owner_approval`, a list of repositories, empty by default. A listed repository lets a trusted merger's explicit approval of a pull request's current head release the hold the hive puts on a pull request that touches a path a person must merge (`auto_merge.human_merge_paths`). The approval can be a GitHub **Approve** review, a `/hive decision approve` reply or a `/hive approve` reply posted after the head. The hive then merges the pull request once CI, review, soak and every other gate pass. A new push needs a new approval, a `hold` a person added is never lifted, and one comment per head records who approved which head. On a listed repository `/hive approve` replies "released for <sha>"; other repositories keep today's rule and reply. The setting is in **Settings → Features → Auto-merge → Per-repository merge policy**, `PUT`/`PATCH /api/config/auto-merge` and the admin MCP's `auto_merge.update` (Danathar/goodreads-mcp#463).
1 change: 1 addition & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -2515,6 +2515,7 @@ func (b *boot) bootAgentsWith(deps bootAgentsDeps) {
// 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.HumanMergeOwnerApproval = func(repo string) bool { return b.cfg != nil && b.cfg.AutoMerge.HumanMergeOwnerApprovalFor(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) }
// Commit messages on a merge-ready head are read for closing keywords
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 @@ -923,6 +923,7 @@ func runAutoMergeSweepIfDue(ctx context.Context, ghClient *github.Client, cfg *c
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.HumanMergeOwnerApproval = func(repo string) bool { return cfg.AutoMerge.HumanMergeOwnerApprovalFor(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 @@ -1561,6 +1562,7 @@ func runIssueUnparkSweepIfDue(ctx context.Context, ghClient *github.Client, cfg
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.HumanMergeOwnerApproval = func(repo string) bool { return cfg.AutoMerge.HumanMergeOwnerApprovalFor(repo) }
approveOpts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(cfg) }
approveOpts.TrustedBotAuthors = func() map[string]bool { return cfg.AutoMerge.TrustedBotAuthorSet() }
approveOpts.TrustedBotSkipReview = func() bool { return cfg.AutoMerge.TrustedBotSkipsReview() }
Expand Down
8 changes: 6 additions & 2 deletions src/docs/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -764,8 +764,9 @@ The keys and names whose values are shown:
`agents.*.backend`, `agents.*.model`, `agents.*.enabled`, `agents.*.paused`,
the API proxy's GitHub API hourly cap `agents.github_api_hourly_cap` and
`agents.*.github_api_hourly_cap`, and the per-repository merge policy: `auto_merge.squash_only[*]`,
`auto_merge.require_current_base[*]` and `auto_merge.human_merge_paths.*[*]`
(the path globs listed under each `owner/repo`). A `*` segment is one map key
`auto_merge.require_current_base[*]`, `auto_merge.human_merge_paths.*[*]`
(the path globs listed under each `owner/repo`) and
`auto_merge.human_merge_owner_approval[*]`. A `*` segment is one map key
and `[*]` any list index.
- **Per-agent GitHub API caps:** the result also carries
`agent_github_api_hourly_caps`, the API proxy's cap as this configuration
Expand Down Expand Up @@ -1195,6 +1196,9 @@ only.
pin-only exception, `{"enabled": true, "paths": [...], "kinds": [...],
"trusted_authors": [...]}`; `null` removes it. An enabled exception needs
`human_merge_paths` for the repository, set already or in the same change.
`human_merge_owner_approval` is a list of `owner/repo` like `squash_only`;
adding a repository is named as widening (a trusted merger's approval
then lets the hive merge its human-merge paths).
`kinds` takes the same list the dashboard offers (`action-sha`,
`image-digest`, `version-pin`, `action-sha-ref`), and the schema says what
each admits. `action-sha-ref` lets a bare `key: <40-hex>` line follow a
Expand Down
2 changes: 1 addition & 1 deletion src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ summary and the `health_deep_read` diagnostic tool.
| `GET` | `/api/config/governor/general-advanced` | Owner only | Settings → General governor settings: `eval_interval_s`, the loop pacing knobs with `loop_defaults`, `explain_mode`, `attribution_trailer`, `api_budget_pacing` (`governor.api_budget_pacing`) and `api_budget_pacing_state` `{enabled, active, factor, effective_interval_s, burn_per_min, reason}`, what the loop is doing with it | `pkg/dashboard/api.go:246` |
| `PUT` | `/api/config/governor/general-advanced` | Owner only | Change those settings; every field is optional and an absent one is left alone. `api_budget_pacing` (boolean) turns GitHub API budget pacing on or off from the next eval cycle. Returns the GET payload | `pkg/dashboard/api.go:247` |
| `GET` | `/api/config/auto-merge` | Owner only | Auto-Merge Config Get | `pkg/dashboard/api.go:251` |
| `PUT` | `/api/config/auto-merge` | Owner only | Auto-Merge Config Set; `human_merge_pin_only` replaces the whole pin-only map (`{}` clears it), and an invalid entry is a 400 with nothing changed; `contributor_lane.workflow_fence_scope_repos` (`{owner/repo: "all", "human_merge_paths" or null}`) sets or clears single repositories' own workflow fence scope (`project.repo_policies[].workflow_fence_scope`) and leaves repositories it does not name, and the hive-wide scope, unchanged; a repository outside `project.repos` or another value is a 400 with nothing changed, and a change is audited per repository | `pkg/dashboard/api.go:252` |
| `PUT` | `/api/config/auto-merge` | Owner only | Auto-Merge Config Set; `human_merge_pin_only` replaces the whole pin-only map (`{}` clears it), and an invalid entry is a 400 with nothing changed; `human_merge_owner_approval` replaces the list of repositories where a trusted merger's approval of the head releases the human-merge-path hold (`[]` clears it; a repository outside `project.repos` is a 400 with nothing changed); `contributor_lane.workflow_fence_scope_repos` (`{owner/repo: "all", "human_merge_paths" or null}`) sets or clears single repositories' own workflow fence scope (`project.repo_policies[].workflow_fence_scope`) and leaves repositories it does not name, and the hive-wide scope, unchanged; a repository outside `project.repos` or another value is a 400 with nothing changed, and a change is audited per repository | `pkg/dashboard/api.go:252` |
| `GET` | `/api/config/convergence` | Owner only | Convergence Config Get | `pkg/dashboard/api.go:258` |
| `PUT` | `/api/config/convergence` | Owner only | Convergence Config Set | `pkg/dashboard/api.go:260` |
| `GET` | `/api/config/governor/advisory` | Owner only | Governor Advisory Get | `pkg/dashboard/api.go:264` |
Expand Down
47 changes: 47 additions & 0 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,53 @@ auto_merge:
- your-org/docs-only-repo
```

### Owner approval releases the human-merge-path hold

`auto_merge.human_merge_owner_approval` is an opt-in list of `owner/repo`
names, empty by default. A repository not listed keeps the rule above: a pull
request touching one of its `human_merge_paths` is held and a person merges
it. In a listed repository a trusted merger's explicit approval of the pull
request's current head releases that hold instead, and the merge lanes merge
the pull request once every other gate passes. CI, required checks,
freshness, soak, review verdicts, other holds and the sentinel all still
apply: the approval is not a merge override.

- **What counts as approval.** A trusted merger's GitHub **Approve** review
on the current head, a `/hive decision approve` reply (typed on the PR or
sent from the dashboard), or a `/hive approve` reply posted after the hive
first saw the head. These are the workflow-path fence's approvals plus
`/hive approve`; an edited comment never counts, and someone who is not a
trusted merger cannot approve.
- **Not the author.** The pull request author's own approval never counts,
whatever form it takes, so one account cannot stand in for the second
person the hold exists to bring in.
- **Bound to the head.** A new push needs a new approval. The one exception
is the fence's: an Approve review or dashboard approval carries over the
hive's own update from the base branch when the PR's diff is unchanged.
- **What is released.** The stage-label pass removes only the `hold` the
human-merge-path gate put on for this refusal, through the shared release
API with its provenance checks: the App's single, unedited, head-stamped
notice, and every `hold` the PR was ever labelled with applied by the App.
A `hold` a person added or re-added is never removed, and neither is one
another hold source explains (a pause, the reporter-trust gate). The
release goes through the write-back gate (`human_merge_path_release`).
- **What is recorded.** One comment per head names who approved which head
(`<!-- hive:human-merge-approval <sha> -->`), and the hive logs
`owner approval released human-merge-path hold`.
- **What `/hive approve` replies.** In a listed repository the reply says
the hold is released for the head and that the hive merges the PR when the
other gates clear, or, when no approval of the current head is recorded
yet, which approvals do it. In other repositories the reply is unchanged.
- **The PR's stage.** An unapproved head parks at `085` asking for the
approval; an approved head goes on through the lanes like any other PR.

Owners set the list from **Settings → Features → Auto-merge → Per-repository
merge policy → Owner approval merges paths a person must merge**, through
`human_merge_owner_approval` on `PUT /api/config/auto-merge`, or with the
admin MCP operation `auto_merge.update`; it applies on the next sweep. A
repository outside `project.repos` is refused. The `hive-merge` relay path is
unchanged: it still refuses such a pull request.

### One human step at L5: approve and unhold

At ACMM L5 an agent PR carries the level `hold`, and Hive cannot merge its own
Expand Down
8 changes: 7 additions & 1 deletion src/docs/maintainer-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,13 @@ that queue flow. A swarm `changes_requested` or `reject` verdict is not
overridden by a human approval; the head must be fixed or merged manually.
Neither form bypasses CI, `hold`-class labels, a sentinel alert or a lane
that only merges by hand (CI workflow / action files edited, tests removed,
an `auto_merge.human_merge_paths` match): the `stage/085-needs-decision`
an `auto_merge.human_merge_paths` match, except in a repository listed in
`auto_merge.human_merge_owner_approval`, where a trusted merger's Approve
review, `/hive decision approve` or `/hive approve` on the current head
releases the hive's human-merge-path hold and the lanes merge the PR once
every other gate passes; see
[hive-merge.md](hive-merge.md#owner-approval-releases-the-human-merge-path-hold)):
the `stage/085-needs-decision`
entry comment names, per lane, what actually clears the park — the trusted
merger's approval, the label a person must remove, or a manual merge
([#13087](https://github.com/hivecommons/hive/issues/13087)). A `/hive
Expand Down
Loading
Loading