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/changed-owner-approval-workflow-fence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Contributor-lane auto-merge: a hive owner / trusted merger's explicit approval on the current head — a GitHub `APPROVED` review on that commit, or a dashboard `/hive decision approve` bound to it — now releases the `contributor-lane:workflow-path` fence, so the hive merges an approved PR editing `.github/workflows/**` / `.github/actions/**` itself instead of parking it at `stage/090-ready-for-human-merge` (`auto_merge.contributor_lane.owner_approval_releases_workflow_fence`, default on). Approval on an older head does not count; a merge refused for want of the App's `workflows: write` marks the PR `hive:unauthorized` (`merge-workflow-path`) and parks the approved head at 090 as before. The 085 note for an unapproved workflow-path PR now reads "awaiting owner approval" (#14664).
23 changes: 12 additions & 11 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -80,17 +80,18 @@ func contributorLanePolicyFunc(cfg *config.Config) func() automerge.ContributorL
p := cfg.AutoMerge.ContributorLane
tier := cfg.AutoMerge.ContributorTier
return automerge.ContributorLanePolicy{
Enabled: p.IsEnabled(),
HiveID: cfg.HiveID,
Soak: time.Duration(p.EffectiveSoakMinutes()) * time.Minute,
RequireReviewerVerdict: p.EffectiveRequireReviewerVerdict(),
Repos: p.RepoSet(),
ExcludeLabels: p.ExcludeLabelSet(),
RequireTiers: p.RequireTierSet(),
RegistryTiersSufficient: p.EffectiveRegistryTiersSufficient(),
AutoPromoteAfterMergedPR: tier.EffectiveAutoPromoteAfterMerged(),
AutoPromotionScope: p.EffectiveAutoPromotionScope(),
ApproveHeldRunsForRegistryTrusted: p.EffectiveApproveHeldRunsForRegistryTrusted(),
Enabled: p.IsEnabled(),
HiveID: cfg.HiveID,
Soak: time.Duration(p.EffectiveSoakMinutes()) * time.Minute,
RequireReviewerVerdict: p.EffectiveRequireReviewerVerdict(),
Repos: p.RepoSet(),
ExcludeLabels: p.ExcludeLabelSet(),
RequireTiers: p.RequireTierSet(),
RegistryTiersSufficient: p.EffectiveRegistryTiersSufficient(),
AutoPromoteAfterMergedPR: tier.EffectiveAutoPromoteAfterMerged(),
AutoPromotionScope: p.EffectiveAutoPromotionScope(),
ApproveHeldRunsForRegistryTrusted: p.EffectiveApproveHeldRunsForRegistryTrusted(),
OwnerApprovalReleasesWorkflowFence: p.EffectiveOwnerApprovalReleasesWorkflowFence(),
}
}
}
Expand Down
2 changes: 1 addition & 1 deletion src/docs/github-app-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Repository permissions used by the dashboard setup UI are:
| Administration | Read-only | Read branch-protection rules before the merge-request watcher lands a PR; Hive refuses closed if it cannot verify the base branch is protected. |
| Commit statuses | Read/write | Needed when `governor.labels.automerge` is the default `lgtm` on a repository running Prow's commit-bound `lgtm` (prow-github-actions v3): the queue action sets a `prow/lgtm` success status on the approved head so Prow does not strip the label. Without the write grant the label and approval still land, but every queue action takes the failure branch and posts a PR comment saying the status could not be set. Choose a distinct label such as `hive/auto-merge` if you would rather keep this at Read. |

| Workflows | Read/write | Let trusted-tier agents push branches that modify `.github/workflows/`. Without it GitHub rejects any GitHub App-token push touching those files server-side ("refusing to allow a GitHub App to create or update workflow … without workflows permission") no matter what the token requests. Maintainer user credentials are separate and can still push workflow-file changes when their account has the normal repository rights; the Hive App cannot until this grant is added **and re-accepted on each installation** (an existing install must approve the new permission under Settings → Integrations → the app → Review request). See [`hive-open-pr`](hive-open-pr.md#workflow-file-pushes-rejected-by-app-tokens) for the agent delivery procedure and [#6985](https://github.com/hivecommons/hive/issues/6985) for the outstanding permission change. |
| Workflows | Read/write | Let trusted-tier agents push branches that modify `.github/workflows/`, and let the contributor lane merge an owner-approved PR that edits `.github/workflows/**` (`auto_merge.contributor_lane.owner_approval_releases_workflow_fence`, [#14664](https://github.com/hivecommons/hive/issues/14664)); without the grant such a merge is refused and the hive marks the PR `hive:unauthorized` (`merge-workflow-path`) and parks it at 090 for a maintainer's **Merge** click. Without it GitHub also rejects any GitHub App-token push touching those files server-side ("refusing to allow a GitHub App to create or update workflow … without workflows permission") no matter what the token requests. Maintainer user credentials are separate and can still push workflow-file changes when their account has the normal repository rights; the Hive App cannot until this grant is added **and re-accepted on each installation** (an existing install must approve the new permission under Settings → Integrations → the app → Review request). See [`hive-open-pr`](hive-open-pr.md#workflow-file-pushes-rejected-by-app-tokens) for the agent delivery procedure and [#6985](https://github.com/hivecommons/hive/issues/6985) for the outstanding permission change. |
Organization permission:

| Permission | Level | Why |
Expand Down
27 changes: 24 additions & 3 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -484,9 +484,29 @@ A PR merges through this tier only when all of the following hold:
skipping every cycle (#12344; #12195, #12290). An unmarked, unregistered
first-timer is still never admitted.
- The diff does not touch `.github/workflows/**` or `.github/actions/**`
(`contributor-lane:workflow-path`) and does not delete a test file or remove
25+ test lines while deleting at least 3× what it adds
(`contributor-lane:tests-removed`).
(`contributor-lane:workflow-path`) — **or** a hive owner / trusted merger
has explicitly approved the current head
(`owner_approval_releases_workflow_fence`, default `true`,
[#14664](https://github.com/hivecommons/hive/issues/14664)). Explicit
approval is a GitHub pull-request review in state `APPROVED` whose commit
is the current head by a login the hive's merger authorizer trusts (the
same bar that releases a `requires_human` verdict), or a dashboard
approval (`/hive decision approve`, which posts `/lgtm` + `/approve`
attributed to the maintainer and bound to the head) or a trusted merger's
own `/hive decision approve` comment posted after the head. Approval on an
earlier head never counts: a new push re-arms the fence and the 085 note
reads "awaiting owner approval … re-approve after a push". When released
the lane logs `workflow-path fence released by owner approval login=…
head=…`, leaves one `<!-- hive:workflow-approval head=… by=… -->` audit
comment per head, and the PR goes through every other gate below like any
other. Merging such a PR needs the App's **Workflows: Read and write**;
when GitHub refuses the merge for want of it the lane marks the PR
`hive:unauthorized` (step `merge-workflow-path`), stops retrying that
head, and the approved head parks at `090-ready-for-human-merge` for a
person's **Merge** click as before. With the toggle off, or with no
approval, a workflow-path PR is never merged by the hive.
- The diff does not delete a test file or remove 25+ test lines while
deleting at least 3× what it adds (`contributor-lane:tests-removed`).
- Required CI is green on the current head, using the same merge-CI gate as
the App self-merge tier.
- A reviewer agent is configured (otherwise `contributor-lane:no-reviewer`:
Expand Down Expand Up @@ -533,6 +553,7 @@ auto_merge:
registry_tiers_sufficient: true # a require_tiers tier on the author's registry profile admits without a claim marker
auto_promotion_scope: hive # count clean merged PRs across every hive repo (repo = this repository only)
approve_held_runs_for_registry_trusted: true # approve action_required runs once per head for registry-admitted authors
owner_approval_releases_workflow_fence: true # a trusted merger's approval on the current head lets the lane merge .github/workflows/** PRs
contributor_tier:
auto_promote_after_merged: 5 # clean merged PRs before the lane trusts an author on its own; negative disables
```
Expand Down
8 changes: 5 additions & 3 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ used to admit the PR:
| CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip — the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:<check>,<check>` ("waiting for the base branch's CI to recover (…) — not this PR's fault"): never 070/071/072, never nudged, never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `<!-- hive-base-branch-red -->` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) |
| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:<check>,<check>`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or approve the run as the repository requires). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273)) |
| any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees ✗). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:<check>` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` → 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) |
| `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `reporter-trust-hold` | human hand-off, **decision** cause → routed by the head's evidence (below); lands at `085-needs-decision` when the head is otherwise clean |
| `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `reporter-trust-hold` | human hand-off, **decision** cause → routed by the head's evidence (below); lands at `085-needs-decision` when the head is otherwise clean. `contributor-lane:workflow-path` reads "awaiting owner approval": a trusted merger's `APPROVED` review on the current head (or a dashboard `/hive decision approve`) releases the fence and the lane merges the PR itself (`owner_approval_releases_workflow_fence`, [#14664](https://github.com/hivecommons/hive/issues/14664)); only with the toggle off, or when the App lacks `workflows: write` for the merge (`hive:unauthorized`, `merge-workflow-path`), does an approved head park at `090-ready-for-human-merge` for a person's click |
| `merge-refused:review-required` (GitHub answered the merge with 405 "At least N approving review(s) is/are required by reviewers with write access"), `merge-refused:method-not-allowed` (405 "Merge commits / Squash merges / Rebase merges are not allowed on this repository") | human hand-off, **decision** cause, as above: lands at `085-needs-decision` when the head is otherwise clean, and the entry comment names the rule GitHub refused the merge on. Every sweep (self-authored, trusted-author, queued, contributor lane) logs these as skips, not `merge-failed` errors, and stops calling merge: a review refusal is remembered per PR head and re-armed when the head moves, when GitHub's `mergeable_state` for the PR changes (an approving review turns `blocked` into `clean`), or after 30 minutes; a method refusal is remembered per repository and method for 30 minutes. The hive never switches the merge method on its own (a forward merge or a `merge-method/merge` PR must not be squashed), so `method-not-allowed` is a manual-merge park. Any other 405, 409 or 422 is still `merge-failed` |
| `contributor-lane:no-claim` / `claim-*` / `author-association` / `no-linked-issue`, `untrusted-author-role`, `author-permission-missing` | human hand-off, **trust** cause → routed by the head's evidence (below); lands at `090-ready-for-human-merge` when the head is otherwise clean |
| hand-offs (`not-app-authored`, `trusted-bot-lane`, `trusted-author:app-authored`, `contributor-lane:app-authored`), transient fetch errors | no opinion — the owning lane decides; nothing is written. An App-authored PR is handed off by the trusted-author and contributor-lane tiers under their own reason; the self-authored lane owns it, and its `review-gate:no-review-bundle` is the stage's reason while the swarm has not reviewed the head ([#14482](https://github.com/hivecommons/hive/issues/14482)) |
Expand Down Expand Up @@ -952,8 +952,10 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
lane re-reads its diff on every pass, so the fix lane rebases and
repairs CI on the PR's branch (074) and the green head lands at
`stage/085-needs-decision` with "a maintainer must review and merge
this PR manually" — the lane never merges it, and the 085 note says
the hive adopted it to repair CI and why it still will not merge it.
this PR manually" — the lane does not merge it unattended, and the 085
note says the hive adopted it to repair CI and why it still will not
merge it (for `workflow-path`, a trusted merger's approval on the
current head releases the fence, [#14664](https://github.com/hivecommons/hive/issues/14664)).
- **supersede** (and the `dco-rehome`, `signoff-rehome` and
`in-place-stalled` second takeovers): the App PR's body opens with
`<!-- hive:carried-fence reason=<contributor-lane:…> from=#<n> -->`
Expand Down
1 change: 1 addition & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,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>`, approve the head's `action_required` workflow runs once (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`, fork heads included), 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 dashboard `/hive decision approve` bound to it — releases the contributor lane's `contributor-lane:workflow-path` fence, so the lane merges a PR editing `.github/workflows/**` / `.github/actions/**` itself once CI, soak and the other gates are clear. Logs `workflow-path fence released by owner approval`, leaves one `hive:workflow-approval` audit comment per head; approval on an older head does not count. 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)). 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). |

Expand Down
15 changes: 15 additions & 0 deletions src/pkg/config/automerge_trusted_bot_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,21 @@ func TestContributorLaneAutoMergeConfigApproveHeldRunsForRegistryTrusted(t *test
}
}

// owner_approval_releases_workflow_fence defaults on so an owner-approved
// workflow-path PR is the hive's to merge; an explicit false keeps every
// workflow-path PR a person's merge (hivecommons/hive#14664).
func TestContributorLaneAutoMergeConfigOwnerApprovalReleasesWorkflowFence(t *testing.T) {
var cfg ContributorLaneAutoMergeConfig
if !cfg.EffectiveOwnerApprovalReleasesWorkflowFence() {
t.Fatal("owner_approval_releases_workflow_fence must default to true")
}
off := false
cfg.OwnerApprovalReleasesWorkflowFence = &off
if cfg.EffectiveOwnerApprovalReleasesWorkflowFence() {
t.Fatal("explicit owner_approval_releases_workflow_fence: false must keep the fence absolute")
}
}

func TestContributorTierAutoMergeConfigAutoPromoteDefault(t *testing.T) {
var cfg ContributorTierAutoMergeConfig
if got := cfg.EffectiveAutoPromoteAfterMerged(); got != DefaultContributorTierAutoPromoteAfterMerged {
Expand Down
Loading
Loading