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/fixed-merge-wording-auto-merge-off.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The 090 "Ready for a human merge" comment no longer names the author's trust role when something else is why a person merges. On a repository whose hive auto-merge is off it said "Blocked only by `role/trusted`"; it now says "Auto-merge is off for this repo, so a person merges." in the same words the dashboard's gate cell uses (the other non-trust reasons — refused merge method, branch protection, missing App permission, reviewer deferred — likewise). Its closing line asks for `/lgtm` `/approve` only when the PR wears Prow's plugin labels; elsewhere it asks the person to approve and merge on GitHub, since nothing there answers `/lgtm`. The workflow-path fence's owner-approval audit comment on an auto-merge-off repository now says a person merges the PR instead of "the hive merges this PR itself" (projectbluefin/website#1036, projectbluefin/actions#757, projectbluefin/actions#752).
8 changes: 7 additions & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -477,10 +477,16 @@ conflict reason and the contributor lane's soak — and
| everything above clean but a sentinel alert or hold-class label on the PR | `090-ready-for-human-merge`, held ([#17327](https://github.com/hivecommons/hive/issues/17327)): the entry comment carries the evidence and adds "Held: a sentinel alert is open on this PR. The hive never merges this head while the gate stands." The gate never changes the stage; it only stops the merge |
| checks still running / unreadable, a required check (branch protection or ruleset) with nothing reported on the head (a PR opened with `GITHUB_TOKEN` triggers no workflow; projectbluefin/utah#1074), or the lane's soak not yet elapsed | `060-reviewed` (not 095: that stage means the lane has *admitted* the head, which a trust-blocked PR never is) |
| everything above clean and only trust in the way | `090-ready-for-human-merge` + one entry comment: "Ready for a human merge: verdict approved @abc1234, 55/55 checks green, DCO yes, soak 1h0m0s elapsed. Blocked only by `role/newcomer` (below require_tiers)." When GitHub reports the head behind a base that requires up-to-date branches, the stage is still 090, but the comment adds "behind `main`" to the digest, says "Blocked by" instead of "Blocked only by", and says GitHub will not merge the head until `main` is merged into it ([projectbluefin/common#1619](https://github.com/projectbluefin/common/issues/1619)) |
| everything above clean and a person merges for another reason: the repo's hive auto-merge is off, the repo refuses the merge method, branch protection wants a review the hive cannot give, the App lacks the merge permission, a reviewer deferred | `090-ready-for-human-merge` + one entry comment that states that reason in the same words the dashboard's gate cell uses (`prstage.HumanMergeReasonWords`), e.g. "Auto-merge is off for this repo, so a person merges.", instead of "Blocked only by `role/…`" ([projectbluefin/website#1036](https://github.com/projectbluefin/website/pull/1036)) |

The entry comments are posted once per stage visit (a flip 085 ↔ 090 is a
new visit) and never as a GitHub review: the hive does not approve on a
maintainer's behalf, so prow/tide see nothing until a person acts. The
maintainer's behalf, so prow/tide see nothing until a person acts. The 090
comment's closing line asks for `/lgtm` `/approve` only when the PR wears
one of Prow's plugin labels (`approved`, `size/*`, `do-not-merge/*`,
`ok-to-test`, `needs-ok-to-test`, `tide/*`); otherwise it asks the person to
approve and merge it on GitHub, since nothing in that repository answers
`/lgtm` ([projectbluefin/actions#757](https://github.com/projectbluefin/actions/pull/757)). The
check digest costs two REST calls per head and is cached 10 minutes; it is
read only for human-routed PRs.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -639,7 +639,7 @@ advanced into the merge path.
| `auto_merge.contributor_lane.auto_promotion_scope` | `hive` | Where the clean-merged-PR ratchet (`auto_merge.contributor_tier.auto_promote_after_merged`) counts an author's merges: `hive` counts across every repository the hive manages (one `search/issues` query finds the repos holding the author's merges; the PR's own repo is always walked first), `repo` counts only the PR's repository. Revert and sentinel-alert evidence blocks promotion in either scope. |
| `auto_merge.contributor_tier.auto_promote_after_merged` | `5` | Clean merged PRs (no revert, no sentinel label, not undone by a later merged revert) after which the contributor lane treats an author as `trusted` without an operator grant, unless the registry marks them `revoked`. Negative disables the ratchet. |
| `auto_merge.contributor_lane.approve_held_runs_for_registry_trusted` | `true` | When the registry path admitted the PR author and the lane stops at `required-check-missing:<ctx>` (or at `ci-unverified` with every `pull_request` run on the head held), approve the head's `action_required` workflow runs once per hive process (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`; only fork `pull_request` runs and Actions-bot runs, the ones GitHub accepts; a 403 is not retried until the head changes or the App gains Actions write), post one `hive:contributor-held-runs-approved` audit comment and log `contributor-lane approved held runs`. Never acts for claim-marker, auto-promoted or association admissions, sentinel/exclude-labelled PRs, or diffs touching `.github/workflows/**`. Needs the App's **Actions: Read and write** permission. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.owner_approval_releases_workflow_fence` | `true` | A hive owner / trusted merger's explicit approval on the **current** head — a GitHub `APPROVED` review on that commit, or a `/hive decision approve` (typed on the PR by the merger, or from the dashboard) bound to it — releases the contributor lane's `contributor-lane:workflow-path` fence (never for a head that also removes tests, which stays `contributor-lane:tests-removed`), so the lane merges a PR editing `.github/workflows/**` / `.github/actions/**` itself once CI, soak and the other gates are clear. The same approval answers a `requires_human` reviewer verdict on that head (a typed one is recorded as the decision, logging `typed approval recorded as the answer to the reviewer's requires_human question`); `/hive approve` answers the verdict but never releases the fence, so on the owner's own PR, where GitHub refuses the self-review, `/hive decision approve` is the one command for both ([Danathar/zfs-aurora-complex#254](https://github.com/Danathar/zfs-aurora-complex/pull/254)). Logs `workflow-path fence released by owner approval`, leaves one `hive:workflow-approval` audit comment per head, which says whether the verdict is answered; approval on an older head does not count, except across the hive's own base refresh: when only GitHub-verified App merges of the base branch (at most five) separate the approved head from the current one and the PR's three-dot diff is unchanged, the approval carries over and the lane logs `workflow-path fence approval carried over hive base refresh`. Any contributor push re-arms the fence. An unmarked approval binds to the PR `updated_at` pinned on the hive's first sweep of the head, not to the push, so one typed between the push and that sweep is judged stale and must be typed again ([#14754](https://github.com/hivecommons/hive/issues/14754)). Needs the App's **Workflows: Read and write**; without it the merge is refused, the PR is marked `hive:unauthorized` (`merge-workflow-path`) and parks at 090 for a person's click. `false` keeps every workflow-path PR a person's merge ([#14664](https://github.com/hivecommons/hive/issues/14664)). A head that also touches `auto_merge.human_merge_paths` is a person's merge either way: the human-merge-path rule refuses it after the approval, so the stage never asks for one and parks the reviewed, green, soaked head at 090 under the human-merge-path reason (a PR the pin-only exception might admit keeps the ask). See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.owner_approval_releases_workflow_fence` | `true` | A hive owner / trusted merger's explicit approval on the **current** head — a GitHub `APPROVED` review on that commit, or a `/hive decision approve` (typed on the PR by the merger, or from the dashboard) bound to it — releases the contributor lane's `contributor-lane:workflow-path` fence (never for a head that also removes tests, which stays `contributor-lane:tests-removed`), so the lane merges a PR editing `.github/workflows/**` / `.github/actions/**` itself once CI, soak and the other gates are clear. On a repository whose hive auto-merge is off the hive never merges, so the audit comment says a person merges it instead ([projectbluefin/actions#752](https://github.com/projectbluefin/actions/pull/752)). The same approval answers a `requires_human` reviewer verdict on that head (a typed one is recorded as the decision, logging `typed approval recorded as the answer to the reviewer's requires_human question`); `/hive approve` answers the verdict but never releases the fence, so on the owner's own PR, where GitHub refuses the self-review, `/hive decision approve` is the one command for both ([Danathar/zfs-aurora-complex#254](https://github.com/Danathar/zfs-aurora-complex/pull/254)). Logs `workflow-path fence released by owner approval`, leaves one `hive:workflow-approval` audit comment per head, which says whether the verdict is answered; approval on an older head does not count, except across the hive's own base refresh: when only GitHub-verified App merges of the base branch (at most five) separate the approved head from the current one and the PR's three-dot diff is unchanged, the approval carries over and the lane logs `workflow-path fence approval carried over hive base refresh`. Any contributor push re-arms the fence. An unmarked approval binds to the PR `updated_at` pinned on the hive's first sweep of the head, not to the push, so one typed between the push and that sweep is judged stale and must be typed again ([#14754](https://github.com/hivecommons/hive/issues/14754)). Needs the App's **Workflows: Read and write**; without it the merge is refused, the PR is marked `hive:unauthorized` (`merge-workflow-path`) and parks at 090 for a person's click. `false` keeps every workflow-path PR a person's merge ([#14664](https://github.com/hivecommons/hive/issues/14664)). A head that also touches `auto_merge.human_merge_paths` is a person's merge either way: the human-merge-path rule refuses it after the approval, so the stage never asks for one and parks the reviewed, green, soaked head at 090 under the human-merge-path reason (a PR the pin-only exception might admit keeps the ask). See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.workflow_fence_scope` | `all` | Which CI workflow / action edits trip the `contributor-lane:workflow-path` fence. `all` fences every edit under `.github/workflows/**` or `.github/actions/**`. `human_merge_paths` fences only a workflow / action file that also matches the repository's `auto_merge.human_merge_paths` (the human-merge hold's matcher), so routine workflow edits go through review, CI and soak without an owner's approval. Fails closed: a repository with no `human_merge_paths` entry keeps the full fence, a renamed workflow / action file always trips it, and a head GitHub refused to merge for want of the App's **Workflows: Read and write** is marked `hive:unauthorized` (`merge-workflow-path`) and stays fenced. The tests-removed fence, Sentinel, the human-merge hold, the held-run approval guard (never for any workflow edit) and adoption's refusal to publish workflow edits upstream are unchanged. Sentinel's default `sensitive_path` list still labels such PRs `sentinel-alert`. Any other value is rejected on save and read as `all`. Owner-only through `PUT /api/config/auto-merge`; Settings → Features → Auto Merge → Contributor-lane auto-merge → **Workflow fence scope**. A repository can set its own value with `project.repo_policies[].workflow_fence_scope`. See [hive-merge.md](../hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.repos` | empty = all watched repos | Optional repo allow-list for the contributor-lane tier (bare name or `owner/repo`). |
| `auto_merge.contributor_lane.exclude_labels` | `hold`, `do-not-merge`, `needs-human`, `blocked`, `needs-rebase` | Labels that keep a PR out of contributor-lane auto-merge (`do-not-merge/*` always excluded; `blocked` is refused by every merge lane whatever this list says, and reads `label:blocked`). |
Expand Down
5 changes: 3 additions & 2 deletions src/pkg/dashboard/stage_tracker_actor.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"strings"
"time"

stageengineprstage "github.com/hivecommons/hive/pkg/stageengine/prstage"
"github.com/hivecommons/hive/pkg/stagelabels"
)

Expand Down Expand Up @@ -256,8 +257,8 @@ func stageTrackerHumanReason(it StageTrackerItem, a *StageTrackerActor) string {
return stageTrackerClipReason(clause)
}
case stagelabels.ReadyForHumanMerge:
if w, ok := stageTrackerHumanMergeReasonWords[it.HumanMergeReason]; ok {
return w[0]
if w, _, ok := stageengineprstage.HumanMergeReasonWords(it.HumanMergeReason); ok {
return w
}
case stagelabels.Fixing, stagelabels.NeedsAuthor, stagelabels.ReturnedToContributor:
if a != nil && a.Login != "" {
Expand Down
21 changes: 3 additions & 18 deletions src/pkg/dashboard/stage_tracker_caption.go
Original file line number Diff line number Diff line change
Expand Up @@ -534,22 +534,6 @@ func stageTrackerManualMergeReason(reason string) bool {
return false
}

// Gate-cell words and tooltips per prstage.HumanMergeReason* code: why a
// person, not the hive, merges a PR parked at 090 (hivecommons/hive#14658).
// Plain words, one short sentence each, no config keys (hivecommons/hive#15394).
var stageTrackerHumanMergeReasonWords = map[string][2]string{
stageengineprstage.HumanMergeReasonWorkflowFiles: {"workflow files", "It changes GitHub workflow files, which hive never merges on its own"},
stageengineprstage.HumanMergeReasonTestsRemoved: {"tests removed", "It removes tests, which hive never merges on its own"},
stageengineprstage.HumanMergeReasonManualMergePolicy: {"manual-merge policy", "It touches files this repo reserves for a person to merge"},
stageengineprstage.HumanMergeReasonBranchProtection: {"branch protection", "Branch protection wants a review hive cannot give; approve on GitHub or merge it"},
stageengineprstage.HumanMergeReasonMergeMethod: {"merge method", "The repo does not allow the merge method this PR needs"},
stageengineprstage.HumanMergeReasonAutoMergeOff: {"auto-merge off", "Auto-merge is off for this repo, so a person merges"},
stageengineprstage.HumanMergeReasonUntrustedAuthor: {"untrusted author", "Hive won't merge it alone — the author isn't a trusted author yet"},
stageengineprstage.HumanMergeReasonUnauthorized: {"hive bot lacks permission", "The hive bot's GitHub App is missing the permission to merge here; a person merges"},
stageengineprstage.HumanMergeReasonReviewerDeferred: {"reviewer deferred", "A reviewer asked for a person to merge this one"},
stageengineprstage.HumanMergeReasonBreakingChange: {"human merge", "Breaking change — owner merges; hive never merges a ⚠️-titled or needs-owner-merge PR"},
}

// stageTrackerHumanMergeReason derives, from a 090 stage reason, the
// compact code, the gate-cell word and the tooltip saying why a person
// must merge. An unrecognised lane reason falls back to the "policy" code
Expand All @@ -559,8 +543,9 @@ func stageTrackerHumanMergeReason(reason string) (code, word, tip string) {
if code == "" {
return "", "", ""
}
if w, ok := stageTrackerHumanMergeReasonWords[code]; ok {
return code, w[0], w[1]
// The words live in prstage so the 090 entry comment says the same.
if w, why, ok := stageengineprstage.HumanMergeReasonWords(code); ok {
return code, w, why
}
base, _ := stagelabels.HumanApprovedReason(reason)
return stageengineprstage.HumanMergeReasonPolicy, "policy", "Hive's merge rules leave this one to a person (`" + strings.TrimSpace(base) + "`)"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,10 @@ func (c *Engine) workflowFenceReleased(ctx context.Context, displayRepo, owner,
} else {
c.info("workflow-path fence released by owner approval", "repo", displayRepo, "pr", number, "login", approver, "head", headSHA)
}
if err := c.commentWorkflowApproval(ctx, owner, repo, number, headSHA, approval, verdictState); err != nil {
// The merge relay's lane gate evaluates on the live engine even for
// an auto-merge-off repo, so the comment must not promise a hive
// merge there (projectbluefin/actions#752).
if err := c.commentWorkflowApproval(ctx, owner, repo, number, headSHA, approval, verdictState, !c.repoAutoMergeAllowed(displayRepo)); err != nil {

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.

Gate on the switched-off state, not 'not allowed':

Suggested change
if err := c.commentWorkflowApproval(ctx, owner, repo, number, headSHA, approval, verdictState, !c.repoAutoMergeAllowed(displayRepo)); err != nil {
if err := c.commentWorkflowApproval(ctx, owner, repo, number, headSHA, approval, verdictState, c.repoObservedOnly(displayRepo)); err != nil {

c.warn("workflow-path fence: could not post audit comment", "repo", displayRepo, "pr", number, "head", headSHA, "error", err)
}
}
Expand Down Expand Up @@ -481,16 +484,23 @@ func workflowApprovalMarker(headSHA string) string {
// owner told only "merges once the gates clear" while the verdict still
// held the PR waited hours for a merge that never came
// (Danathar/zfs-aurora-complex#254). A carried approval names the head it
// was given on (from=) and says why it still stands.
func workflowApprovalComment(headSHA string, approval workflowApproval, verdictState int) string {
// was given on (from=) and says why it still stands. On a repo whose hive
// auto-merge is off (autoMergeOff) the hive never merges, so the comment
// says a person does (projectbluefin/actions#752 was told "the hive merges
// this PR itself" and sat open).
func workflowApprovalComment(headSHA string, approval workflowApproval, verdictState int, autoMergeOff bool) string {
approver := approval.Login
marker := workflowApprovalMarker(headSHA) + " by=" + strings.ToLower(approver)
gates := "the hive merges this PR itself once the usual gates (CI, soak, holds, review verdict) are clear."
merges, offNote := "the hive merges this PR itself", ""
if autoMergeOff {
merges, offNote = "a person merges it", " (auto-merge is off for this repository, so the hive never merges it)"
}
gates := merges + " once the usual gates (CI, soak, holds, review verdict) are clear" + offNote + "."
switch verdictState {
case workflowApprovalVerdictAnswered:
gates = "the same approval answers the review swarm's `requires_human` question on this head, and the hive merges this PR itself once the usual gates (CI, soak, holds) are clear."
gates = "the same approval answers the review swarm's `requires_human` question on this head, and " + merges + " once the usual gates (CI, soak, holds) are clear" + offNote + "."
case workflowApprovalVerdictOpen:
gates = "the review swarm's `requires_human` verdict on this head still holds the PR. A trusted merger's `/hive decision approve` reply (or the dashboard's approval) answers it, as does a `/hive approve` reply posted after the verdict; then the hive merges this PR itself once the usual gates (CI, soak, holds) are clear."
gates = "the review swarm's `requires_human` verdict on this head still holds the PR. A trusted merger's `/hive decision approve` reply (or the dashboard's approval) answers it, as does a `/hive approve` reply posted after the verdict; then " + merges + " once the usual gates (CI, soak, holds) are clear" + offNote + "."
}
if approval.CarriedFrom != "" {
// The approval was on an earlier head; head only merges the base in
Expand All @@ -504,9 +514,9 @@ func workflowApprovalComment(headSHA string, approval workflowApproval, verdictS

// commentWorkflowApproval posts the audit comment once per head: an existing
// marker on the PR, or a prior effects claim, suppresses it.
func (c *Engine) commentWorkflowApproval(ctx context.Context, owner, repo string, number int, headSHA string, approval workflowApproval, verdictState int) error {
func (c *Engine) commentWorkflowApproval(ctx context.Context, owner, repo string, number int, headSHA string, approval workflowApproval, verdictState int, autoMergeOff bool) error {
marker := workflowApprovalMarker(headSHA)
body := workflowApprovalComment(headSHA, approval, verdictState)
body := workflowApprovalComment(headSHA, approval, verdictState, autoMergeOff)
_, err := effects.Execute(hgithub.WithRESTCaller(ctx, workflowApprovalRESTCaller), c.mutation, effects.Claim{
Repo: owner + "/" + repo,
Kind: effects.KindIssueComment,
Expand Down
Loading
Loading