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-held-run-approve-once.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- automerge: the contributor lane's held-run approval now tries each PR head once per process instead of once per sweep. The once-per-head mark lived on the one-shot engine each sweep builds, so a head GitHub refused with 403 (the App lacks `actions: write`) was re-POSTed every ~80 s; on projectbluefin two PRs spent ~270 charged calls an hour on `POST actions/runs/{id}/approve` that could never succeed. The refusal stands, with the existing `hive:unauthorized` note and label, until the head changes or the App gains `actions: write`. Held runs GitHub's approve endpoint never accepts (anything but a fork `pull_request` run or an Actions-bot run) are no longer sent.
2 changes: 1 addition & 1 deletion src/docs/github-app-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Fine-grained PATs are supported β€” the token is sent as a plain bearer, same as
| Actions | Read and write | Read and write | Read and write β€” needed by the default-on gated-run approval sweep (`governor.ci.auto_approve_workflows`); Read suffices with it set to `false`, see below |
| Commit statuses | Read | Read | Read and write β€” needed when `governor.labels.automerge` is the default `lgtm` on a Prow repository, so the queue action can set the `prow/lgtm` status beside the label. With only Read, every queue action still applies the label but posts a PR comment that the status could not be set. |

Since the gated-run approval sweep (`governor.ci.auto_approve_workflows`, **default on**, [#16603](https://github.com/hivecommons/hive/issues/16603)) Hive approves `action_required` `pull_request` runs with the App token β€” `POST /actions/runs/{id}/approve`, once per PR head, for Dependabot/Renovate/App-authored or -triggered runs and for heads a verified owner or merger admitted from the dashboard β€” which needs **Actions: Read and write**. With only **Actions: Read** the call fails with `403`, the hive records one `permission_error` in `/api/status` `workflow_approvals`, logs `workflow approval refused; needs workflow approval on GitHub`, and the CI caption reads `CI waiting Β· needs workflow approval on GitHub`; the refusal is recorded per PR head and not retried, so granting the permission afterwards takes effect for new heads (or after a hive restart), while an already-refused head needs **Approve and run** on GitHub or a fresh push; set `governor.ci.auto_approve_workflows: false` to stay on Read and leave approvals to the `/ok-to-test` workflow described below. The other direct approval Hive performs β€” a contributor-lane PR whose author the contributor registry admitted at a `require_tiers` tier (`auto_merge.contributor_lane.approve_held_runs_for_registry_trusted`, default on) β€” needs the same grant. For that path it is **optional**: without it the call fails with `403 Resource not accessible by integration`, the hive labels the PR `hive:unauthorized`, posts one comment naming the permission and the human step (**Approve and run** on the checks banner or Actions tab, with the run ids), logs `lane unauthorized` once per head, parks the PR at 085 (`Awaiting human: approve workflow runs` in the activity monitor), and clears all of it the tick the required checks report ([#14589](https://github.com/hivecommons/hive/issues/14589)). When GitHub leaves same-repository `pull_request` runs in `action_required` on trusted Dependabot/Renovate/App PRs or registry-trusted `author/clanker` PRs, and the approval sweep is off or lacks the grant, Hive posts `/ok-to-test` once for that head and reports `workflow-approval-required:<ctx>` / `stage/085-needs-decision` until the repository's own self-contained `hive-ok-to-test` workflow approves the held runs. The approval is performed by that repository's `GITHUB_TOKEN` through `.github/workflows/hive-ok-to-test.yml`; that path needs no Prow and no Hive App Actions-write grant, and it never covers fork heads. Fork heads are reached only by the two App-token paths above β€” the gated-run approval sweep and the registry-trusted contributor lane β€” since GitHub holds only fork `pull_request` runs behind the gate; a trusted head's workflow files then run on the repository's runners, which is what the **Actions: Read and write** grant buys. No path approves runs on PRs carrying `sentinel-alert`.
Since the gated-run approval sweep (`governor.ci.auto_approve_workflows`, **default on**, [#16603](https://github.com/hivecommons/hive/issues/16603)) Hive approves `action_required` `pull_request` runs with the App token β€” `POST /actions/runs/{id}/approve`, once per PR head, for Dependabot/Renovate/App-authored or -triggered runs and for heads a verified owner or merger admitted from the dashboard β€” which needs **Actions: Read and write**. With only **Actions: Read** the call fails with `403`, the hive records one `permission_error` in `/api/status` `workflow_approvals`, logs `workflow approval refused; needs workflow approval on GitHub`, and the CI caption reads `CI waiting Β· needs workflow approval on GitHub`; the refusal is recorded per PR head and not retried, so granting the permission afterwards takes effect for new heads (or after a hive restart), while an already-refused head needs **Approve and run** on GitHub or a fresh push; set `governor.ci.auto_approve_workflows: false` to stay on Read and leave approvals to the `/ok-to-test` workflow described below. The other direct approval Hive performs β€” a contributor-lane PR whose author the contributor registry admitted at a `require_tiers` tier (`auto_merge.contributor_lane.approve_held_runs_for_registry_trusted`, default on) β€” needs the same grant. For that path it is **optional**: without it the call fails with `403 Resource not accessible by integration`, the hive labels the PR `hive:unauthorized`, posts one comment naming the permission and the human step (**Approve and run** on the checks banner or Actions tab, with the run ids), logs `lane unauthorized` once per head, parks the PR at 085 (`Awaiting human: approve workflow runs` in the activity monitor), does not POST that head again until it changes or the installation gains **Actions: Read and write** (unlike the gated-run sweep above, the contributor lane re-reads the grant at most every five minutes and tries a refused head once more when it appears; a restart also tries each head once more), and clears all of it the tick the required checks report ([#14589](https://github.com/hivecommons/hive/issues/14589)). When GitHub leaves same-repository `pull_request` runs in `action_required` on trusted Dependabot/Renovate/App PRs or registry-trusted `author/clanker` PRs, and the approval sweep is off or lacks the grant, Hive posts `/ok-to-test` once for that head and reports `workflow-approval-required:<ctx>` / `stage/085-needs-decision` until the repository's own self-contained `hive-ok-to-test` workflow approves the held runs. The approval is performed by that repository's `GITHUB_TOKEN` through `.github/workflows/hive-ok-to-test.yml`; that path needs no Prow and no Hive App Actions-write grant, and it never covers fork heads. Fork heads are reached only by the two App-token paths above β€” the gated-run approval sweep and the registry-trusted contributor lane β€” since GitHub holds only fork `pull_request` runs behind the gate; a trusted head's workflow files then run on the repository's runners, which is what the **Actions: Read and write** grant buys. No path approves runs on PRs carrying `sentinel-alert`.

Install the workflow in each governed repository: run `hivectl ok-to-test-template > .github/workflows/hive-ok-to-test.yml` against your hive (it reads the App bot login from `/api/config`; pass `--app-login <your-app>[bot]` to override), or copy `src/docs/templates/hive-ok-to-test.yml` and replace `HIVE_APP_LOGIN[bot]` with the App bot login shown by Hive for that installation.

Expand Down
15 changes: 11 additions & 4 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -881,15 +881,22 @@ at `required-check-missing:Audit production dependencies` until an operator
clicked "Approve and run". When the registry path admitted the author and the
lane stops at `required-check-missing:<ctx>`, or at `ci-unverified` while
every `pull_request` run on the head is held (the branch's required checks
are unreadable or empty), it now approves the head's held runs once (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`, fork head
included), posts one `<!-- hive:contributor-held-runs-approved … -->` audit
are unreadable or empty), it now approves the head's held runs once (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`). Only runs
GitHub's endpoint accepts are sent: a fork `pull_request` run, or a run the
Actions bot queued; any other held run (a same-repository run, a
`pull_request_review` or `pull_request_target` run) would get 403 on every
try and stays a person's click. It posts one `<!-- hive:contributor-held-runs-approved … -->` audit
comment naming the author and tier, and logs `contributor-lane approved held
runs` with the run ids (`approve_held_runs_for_registry_trusted`, default
`true`). Claim-marker, auto-promotion and association admissions are never
approved for, nor is a PR carrying the sentinel or an `exclude_labels` label,
nor one touching `.github/workflows/**`. The App needs **Actions: Read and
write** for the call; without it the approve fails, is logged once per head,
and the PR waits for a person as before.
write** for the call; without it the approve fails, the PR is marked
`hive:unauthorized` once per head, and it waits for a person as before. The
pass and the refusal are kept for the life of the hive process (not per
sweep; an entry no sweep has touched for 24 hours is dropped), so a refused head is not POSTed again until it changes or the App
gains **Actions: Read and write** (read from the installation at most every
five minutes); a restart tries each head once more.

The required checks come from classic branch protection first. When classic
protection says nothing is required (the branch is unprotected, or protected
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 @@ -551,7 +551,7 @@ advanced into the merge path.
| `auto_merge.contributor_lane.registry_tiers_sufficient` | `true` | Admit a PR whose author's contributor-registry profile carries a `require_tiers` tier without a linked issue or `hive:claim` marker (logged as `contributor-lane:registry-trusted`). All other gates still apply. `false` requires the claim marker for every contributor. |
| `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 (`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.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)). 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
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:5465-5475`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5470-5480`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes β†’ refactors/docs β†’ tests).
Expand Down
Loading
Loading