Skip to content

✨ auto-merge: an owner's approval of the head releases the human-merge-path hold (opt-in per repo) - #19015

Merged
hivecommons-hive[bot] merged 8 commits into
hivecommons:v6from
Danathar:feat/human-merge-owner-approval
Nov 18, 2026
Merged

hivecommons-hive[bot] merged 8 commits into
hivecommons:v6from
Danathar:feat/human-merge-owner-approval

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

Summary

Today a PR that touches a path in auto_merge.human_merge_paths is held, and a person must merge it by hand, even after the owner approves it. On Danathar/goodreads-mcp#463 the owner approved the head with /hive approve, GitHub required no review and reported the PR clean, and the hive still said a person must merge it.

This PR adds an opt-in, per-repository key, auto_merge.human_merge_owner_approval (a list of owner/repo, empty by default). In a listed repository a trusted merger's explicit approval of the PR's current head releases the hive's human-merge-path hold. The hive then merges the PR once CI, review, soak, other holds, the sentinel and every other gate pass. The approval is not a merge override. Repositories not listed behave exactly as today, including the /hive approve reply.

What counts as approval

These come from a trusted merger, bound to the current head:

  • a GitHub Approve review;
  • /hive decision approve, typed or from the dashboard;
  • /hive approve posted after the hive first saw the head. This is new for this feature; the workflow fence still ignores it.

A new push needs a new approval. The fence's one carry-over still applies: an approval survives the hive's own update from the base branch when the diff is unchanged. Edited comments never count.

What is released, and what never is

  • The stage-label pass removes only the hold the gate put on, with the same provenance checks as the existing pin-only release:
    • the App's single, unedited, head-stamped notice;
    • every hold application in the PR's history being the App's.
  • Never released:
    • a hold a person added or re-added;
    • a hold another source explains (pause, reporter trust);
    • anything the write-back gate (human_merge_path_release) refuses.
  • After the release, the gate lets the approved head through instead of re-holding it. The next push re-arms the hold.
  • Audit: one comment per head names who approved which head, plus a log line.

What people see

  • /hive approve on a listed repository: "released for <sha>; merges when the other gates clear". When no approval of the head is recorded yet, it lists the approvals that would release the hold.
  • 085 stage: an unapproved head asks for that approval instead of "merge manually".
  • Settings: Settings → Features → Auto-merge → Per-repository merge policy has a multi-select with a help mark.
  • API and MCP: PUT/PATCH /api/config/auto-merge takes the list and returns a 400 for a repository outside project.repos. The admin MCP's auto_merge.update previews and confirms it, and adding a repository is named as widening.

Not changed

  • Defaults: the key is empty, so nothing changes until an owner lists a repository.
  • The hive-merge relay still refuses these PRs.
  • The contributor-lane workflow fence and dns-failover#181 are out of scope.
  • When a head trips both the workflow fence and a human-merge path, the /hive approve reply keeps today's text.

Notes against the brief

  • ReleaseHumanMergePathHold had no production callers, and it refuses the head the hold was put on, which is the case here. So I split it into a shared body. The pin-only rules are unchanged, and ReleaseApprovedHumanMergePathHold adds the approved-head rules.
  • workflowFenceApproval does not count /hive approve, the command used on goodreads-mcp#463. This feature adds it with the typed decision's head binding.
  • The lanes skip a held PR before they reach the gate, so the release happens in the stage-label pass.

Tests

  • pkg/github: approved-mode release table:
    • releases a hold on the same head and a hold the App re-added;
    • refuses a person's hold, a history that ends removed, and a write-back refusal;
    • pin-only still refuses the same head.
  • pkg/github/automerge:
    • the stage pass releases on an approved head, and keeps the hold when the repo is unlisted, the approver is untrusted, the approval is for an older head, or a person re-added the hold;
    • /hive approve head binding;
    • audit text;
    • /hive approve reply: listed and unlisted (exact current text).
  • pkg/stagelabels: 085 actions.
  • pkg/dashboard:
    • API round-trip, the 400 and clearing;
    • the control and its staging (node).
  • pkg/adminmcp: preview, confirm and widening.
  • pkg/config: the lookup.

Run locally:

  • gofmt -l
  • node --check
  • check-docs-citations.py, check-docs-links.py, check-api-reference-citations.sh
  • dashboard bundle rebuilt

Not run: go test, go build and go vet, per AGENTS.md. CI decides.

Appendix: code

  • Key and lookup: src/pkg/config/review_config.go (HumanMergeOwnerApproval, HumanMergeOwnerApprovalFor)
  • Approval, gate exemption, release, audit, reply: src/pkg/github/automerge/automerge_human_merge_owner_approval.go
  • Gate hook: src/pkg/github/automerge/automerge_human_paths.go (humanMergePathGate)
  • Stage-pass release: src/pkg/github/automerge/automerge_stage_labels.go (beside liftStaleHumanMergePathHold)
  • Release core: src/pkg/github/human_merge_path_release.go
  • 085 route: automerge_stage_human.go, automerge_human_merge_path_fence.go, src/pkg/stagelabels/human.go, src/pkg/stageengine/prstage/causes.go
  • Reply: src/pkg/github/automerge/pr_approve_command.go
  • Wiring: src/cmd/hive/main.go, src/cmd/hive/main_sweeps.go
  • Dashboard: src/pkg/dashboard/api_config_automerge.go, static-src/js/config-features.js, config-helpers.js
  • Admin MCP: src/pkg/adminmcp/tools_automerge_ops.go, tools_settings.go; effective-config key list src/pkg/dashboard/diag_config_value_keys.txt

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…e-path hold (opt-in per repo)

New key auto_merge.human_merge_owner_approval, a list of owner/repo,
empty by default. On a listed repository a trusted merger's explicit
approval of a PR's current head releases the hold the human-merge-path
gate put on it, and the merge lanes merge the PR once CI, review, soak
and every other gate pass. Unlisted repositories keep today's rule and
`/hive approve` reply word for word.

- Approval: the workflow-path fence's (workflowFenceApproval: Approve
  review, dashboard approve, typed /hive decision approve) plus a
  trusted merger's /hive approve posted after the head was first seen.
- Release: the stage-label pass, next to the stale-head lift, through
  ReleaseApprovedHumanMergePathHold. It shares the pin-only release's
  provenance checks, widened only so it may lift the hold on the head it
  was put on and a hold the App re-added on a later head; any person's
  hold application, another hold source, or a write-back refusal keeps
  the hold. The gate lets an approved head through instead of re-holding.
- Audit: one comment per head names the approver and head, plus a log
  line.
- 085 route asks for the approval instead of a manual merge; the
  /hive approve reply says "released for <sha>".
- Dashboard multi-select with help mark, PUT/PATCH validation (400 for a
  repo outside project.repos), admin MCP auto_merge.update row.
- Docs: hive-merge.md section, maintainer-commands.md, settings.md,
  admin-mcp.md, api-reference.md; changelog fragment.

Refs Danathar/goodreads-mcp#463.

Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 18, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 18, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review (head a8efb46): no blockers. The change follows the repo's idioms: marker-comment audit trail, // writeback:gated annotations, a shared release body with the pin-only rules intact, and docs plus a changelog fragment.

Advisory notes, all inline:

  • automerge_human_merge_owner_approval.go uses both listIssueComments and listAllIssueComments, which behave the same. Pick one.
  • The writeback.Item and HiveAuthored construction appears twice and could be one helper.
  • human_merge_path_release.go has a redundant first/last nil check.

-- hive: agent=ci-maintainer backend=claude model=claude-sonnet-5-5 claude=2.1.327

return false
}
number := pr.GetNumber()
comments, err := c.listIssueComments(ctx, owner, repo, number)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style: this file mixes listIssueComments (here and in the reply) with listAllIssueComments (stage-pass paths). Both paginate fully, so pick one to avoid implying a difference.

appBot := strings.TrimSpace(c.transport.AppBotLogin())
author := hgithub.SafeGetLogin(pr.GetUser())
item := writeback.Item{Number: number, IsPR: true, Author: author, Labels: labelNames(pr.Labels), CreatedAt: pr.GetCreatedAt().Time,
HiveAuthored: appBot != "" && strings.EqualFold(normalizeBotLogin(author), normalizeBotLogin(appBot))}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style: the writeback.Item literal with the HiveAuthored comparison is built here and again near line 207. A small helper would keep it in one place.

eventsOpts.Page = resp.NextPage
}
if applied == nil {
if first == nil || last == nil || last.GetEvent() != "labeled" {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style: first and last are set together, so first == nil || last == nil can be just last == nil.

@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • check-failure

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

This is a merge/trust-policy change, so I am routing it rather than judging the code alone.

What I read (first ~300 lines of the diff; the stage-label release logic and the dashboard/UI parts were beyond what I opened): the new opt-in key is wired consistently through src/cmd/hive/main.go:2518, src/cmd/hive/main_sweeps.go:926 and :1565, the config accessor HumanMergeOwnerApprovalFor in src/pkg/config/review_config.go, and the admin MCP field in src/pkg/adminmcp/tools_automerge_ops.go:116, which correctly marks adding a repository as widening. The default is empty, so nothing changes until an owner lists a repository, and the config and MCP tests cover the accessor and the widening disclosure.

Why a person should decide: human_merge_paths is the fence around workflow, CODEOWNERS and hook files. This PR adds a way for a /hive approve comment (which the workflow fence deliberately ignores today, per the PR body) to lift that fence. Whether a comment command should carry that authority, and who counts as a "trusted merger" for it, is the policy question; I could not settle it from the code. I did not review the release path that removes the hold label (provenance checks, write-back gate), so a maintainer or a second pass should look there.

Suggestion, not a defect: the PR has no Closes/Refs to a hivecommons/hive issue (the motivating case is Danathar/goodreads-mcp#463), so linking an in-repo issue would make the decision easier to track.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review at a8efb46. I found no in-scope blocker, and one low advisory.

/hive approve approvals are judged against the in-memory pinned headObservedAt (automerge_human_merge_owner_approval.go:106, automerge_head_age.go:138-155). After a restart or a 7-day prune the pin is re-taken from the current PR updated_at. By then the approval comment, the label removal and the audit comment have all bumped updated_at, so the approval reads as older than the head. A PR still waiting on CI or soak is re-held by humanMergePathGate, and the owner must type /hive approve again. This fails closed. The GitHub Approve review path is bound to the head SHA and is not affected. Treating the existing hive:human-merge-approval <head> marker as proof of an earlier approval would remove the surprise.

The rest of the change looks correct. The provenance widening in releaseHumanMergePathHold is covered by the table test. The pin-only path still refuses a same-head hold. I did not run the tests.

Review findings from reviewer (folded here because this head already carries its hive review):

Two things for this PR at head a8efb46.

1. CI is red. TestHumanMergeApprovalCommentNamesApproverAndHead fails in pkg/github/automerge (job test (rest 1/4), on every rerun), and coverage and test fail with it. It needs a fix before merge.

2. Policy decision. This changes merge/trust policy: an approval releases the hold that human_merge_paths places so a person merges. I read automerge_human_merge_owner_approval.go: approval is bound to the current head, edited comments are ignored, the approver must be a trusted merger, and the release re-checks hold provenance. The key defaults to empty. The mechanics look careful to me, but whether this relaxation should exist is a maintainer call.

I have not approved or closed anything.

Evidence bundle `#190154655c9b` sha256:614e595e0f4bb486d34f2d140443b5107b13b533c50c7e3df269c67f5f6791b1 — download from the dashboard or `hivectl review evidence #19015`.

merged by Hive trusted-author auto-merge: author Danathar holds role owner and GitHub permission maintain on repo; CI green at 61f088c.

…al comment

humanMergeApprovalComment renders the head via stagelabels.ShortSHA,
which trims to 7 characters; the test asserted an 8-character prefix,
so it failed on every run. Assert the exact backticked 7-char form.

Hive-Run: hivecommons#19015
Hive-Plan: fix-pr check-failure
Hive-Spec: auto_merge.human_merge_owner_approval#audit-comment

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Needs a decision, not a merge:

  • the reviewer swarm returned requires_human @31f64bf
  • the review found: the reviewer marked this change high-risk
  • reviewer question: @clubanderson should a trusted merger's single approval (including a bare /hive approve reply) be able to release the hold on auto_merge.human_merge_paths for opted-in repositories, which widens the merge-trust policy?
  • the automerge lane will not merge this unattended

Head: verdict requires_human @31f64bf, 65/67 checks green, 2 pending, DCO yes, soak 0s of 10m0s.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

Updated 2026-11-18 16:29 UTC.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

✅ Resolved: no conflicting open PRs or same-file overlaps remain against v6.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should a trusted merger's single approval (including a bare /hive approve reply) be able to release the hold on auto_merge.human_merge_paths for opted-in repositories, which widens the merge-trust policy?

Routing, not a defect report. This PR adds an opt-in per-repo setting that lets the App merge PRs touching human_merge_paths (often workflow, CODEOWNERS and hook files) after one trusted-merger approval of the head. That is a merge and trust policy change, so a maintainer should decide whether it lands.

What I read in automerge_human_merge_owner_approval.go: the design is careful. The release is opt-in and off by default. Approval is bound to the head, and an edited comment never counts. /hive approve must be posted after the head. Only an App-placed hold is removed, via the provenance check in ReleaseApprovedHumanMergePathHold, and another hold source blocks the release. One audit comment is posted per head. Admin-MCP adds are flagged as widening. Tests cover config, MCP, dashboard, stagelabels and the automerge path.

Open questions for the decider (not verified as defects):

  • /hive approve is newly accepted as approval (humanMergeOwnerApprovalFor, the loop over comments). Does isTrustedMerger or workflowFenceApproval exclude the PR author approving their own head? I did not find that check in the new file; if a trusted merger can author a PR touching these paths and approve it themselves, one account replaces the two-person path.
  • The setting covers every path in human_merge_paths for the repo, with no per-path scoping. Is that intended for repos that list workflow files?

Looks internally consistent otherwise; CI state is not in my verdict.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs are thorough elsewhere, but the operator-reference key tables (src/docs/operator-reference/README.md:305, :615) still say a person must merge and have no row for auto_merge.human_merge_owner_approval. Suggested row is in the inline comment.

Findings not on a changed line

  • src/docs/operator-reference/README.md:615: Docs gap: this auto_merge.human_merge_paths row (and the one at line 305) says a person must merge the PR, with pin-only as the only skip. It does not mention the new auto_merge.human_merge_owner_approval, and no key row exists for it. Add a row, e.g.:

    +| `auto_merge.human_merge_owner_approval` | `[]` (off) | List of `owner/repo`. In a listed repository a trusted merger's approval of the current head (Approve review, `/hive decision approve`, or `/hive approve` after the head was seen) releases the human-merge-path `hold`; every other gate still applies. See [hive-merge.md](../hive-merge.md#owner-approval-releases-the-human-merge-path-hold). |

    and append to this row: 'except in a repository listed in auto_merge.human_merge_owner_approval'.

-- hive: agent=adjudicator backend=claude model=claude-sonnet-5-5 claude=2.1.327

Danathar and others added 4 commits November 18, 2026 17:33
…-merge-path hold

Review asked whether a trusted merger who authors a PR touching a
human_merge_paths file could approve it themselves. They could (typed
/hive decision approve or /hive approve); reject any approval whose login is
the PR author. Also add the missing auto_merge.human_merge_owner_approval row
to the operator reference.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@hivecommons-hive
hivecommons-hive Bot merged commit f9389db into hivecommons:v6 Nov 18, 2026
74 of 75 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant