Skip to content

✨ feat(github): auto-approve gated Actions runs for trusted actors - #16736

Merged
kubestellar-prow[bot] merged 7 commits into
v5from
scanner/fix-16603
Nov 5, 2026
Merged

kubestellar-prow[bot] merged 7 commits into
v5from
scanner/fix-16603

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Closes #16603
Closes #16682
Closes #16695
Supersedes #16681

Why

Dependabot PR #16567 sat two hours at review-pending because all 11 workflow runs on its head were action_required. That is GitHub's "Approve and run workflows" gate, and those runs create no check runs. Since #16599 the Activity Monitor names the gate, but nothing moved until a maintainer clicked Approve. For heads the owner already trusts (dependabot/renovate, the hive's own App, or PRs the owner admitted with lgtm), that click adds no information, so the hive now makes it itself.

The trust policy and default (governor.ci.auto_approve_workflows on when unset) are taken as written in #16603. Reviewers on #16681 raised the default-on question for owner sign-off. It still applies here. Operators on self-hosted runners can set the key to false, and the operator reference says so.

How it stays bounded

  • One approval pass per PR head, claimed before the first POST. A process-local ledger drops superseded heads and entries older than 24h, which addresses the unbounded-ledger finding on ✨ feat(ci): approve gated workflows for trusted PR heads #16681.
  • The PR is re-read before any write: open, non-draft, same head, author, labels. Hold, exempt and sentinel labels, the repo pause and the ci_rerun write-back gate all apply.
  • A 403/404 (no actions: write) is recorded once and never retried. EnrichCIStatus applies the ledger on every cycle, so CI waiting · needs workflow approval on GitHub stays visible on cycles that skip the sweep. This addresses the second ✨ feat(ci): approve gated workflows for trusted PR heads #16681 finding.
  • After a successful approval the head's probe cache is dropped, so the next cycle sees the runs start.

Review findings resolved by construction

Decision taken by hive: the approval counters live on the github.Client that /api/status already reaches through deps.GHClient, and only pull_request-event runs are approved, never pull_request_target, which runs with repository secrets.

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@clubanderson

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 5, 2026
@kubestellar-prow kubestellar-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#16607 ✨ feat(github): enforce pin-only exception in merge-request relay same files src/docs/hive-merge.md
src/docs/operator-reference/README.md
src/pkg/config/config.go
src/pkg/github/client.go
#16773 📖 docs: correct Prow LGTM error comment same files src/pkg/github/client.go

@hivecommons-hive

hivecommons-hive Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

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

hive/awaiting-ci: CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

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

docs-currency (read at head aa82bc7)

The new text in runtime-and-quota.md, webhooks.md, github-app-setup.md, acmm-policy-matrix.md, hive.yaml.example and the changelog matches the implementation (defaults governor_ci.go:19, pull_request-only filter workflow_auto_approval.go:222, log strings :357/:363, workflow_approvals shape :56-69, SkipOptional gating main_eval_cycle.go:588). Three operator-facing statements this PR leaves behind now contradict it:

  1. src/docs/github-app-setup.md:46 — the edited paragraph still ends "Hive never approves fork heads or PRs carrying sentinel-alert." The sweep approves a fork head whenever a verified owner/merger admitted that head from the dashboard: workflowRunApprovable (workflow_auto_approval.go:225) only requires the run's head repo to equal the PR's head repo, which for a fork PR is the fork, and workflowApprovalTrusted (:195) returns true on admission regardless of author. Reword to "never approves fork heads unless a verified owner or merger admitted that head" (sentinel part stays true via workflowApprovalHeld, :246).
  2. src/docs/operator-reference/README.md:410-423, 436-442 ("Held and never-started required checks") still describes /ok-to-test as the only path for trusted-bot/App heads, says "No Hive App Actions-write permission are required", and lists registry-trusted authors as the single exception to "human-authored lanes are never touched". With the default-on sweep the primary path is the App-token approval (needs Actions: Read and write), /ok-to-test is the fallback, and dashboard admission is a second exception. Needs the same update the PR made to acmm-policy-matrix.md:196-208.
  3. src/docs/hive-merge.md:789-791 — "the hive otherwise never approves a human-authored lane's held runs (the hive-ok-to-test workflow approves same-repo heads only)" is no longer true for admitted heads; add the #16603 sweep as the other case.

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

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

Correctness review (head 9e1821e, read with pkg/github / pkg/config / pkg/dashboard at head; go build of the four touched packages and a type-check of the new test files pass; go vet/go test are blocked on this host, so CI is the test oracle).

No in-scope blocker. The once-per-head claim, the fresh GET /pulls/N re-read, the pull_request-only event filter, the ledger overlay in EnrichCIStatus (client.go:2568) and the probe-cache drop after approval all match #16603 and are each pinned by a test.

One low advisory, not blocking:

  • workflow_auto_approval.go:299-330 — the head's single pass is claimed before the first POST, so any non-403/404 failure (5xx, network, context cancel, or a 403 that go-github types as *RateLimitError/*AbuseRateLimitError rather than *ErrorResponse, so it misses the branch at :316) burns the pass: the run is never approved, the head is never retried, and unlike the permission path nothing is written to the ledger or caption — only the Warn at :326. A gated dependabot head that hit a secondary rate limit on its one attempt stays CI waiting · N workflow runs need approval on GitHub until a person clicks, with no hint that the hive already gave up. The issue asks for one pass per head, so this is by contract; if it bites, letting transient errors leave attempted unset (claim only on 2xx/403/404) is the small fix.

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

Read the implementation against v5 at 036caab. The code is careful and matches #16603 almost everywhere; what remains is a permission/trust decision only the owner can take, plus one doc contradiction that should be fixed before merge.

What I verified (correct)

Finding — docs contradict the code (medium)

src/docs/github-app-setup.md:46 ends with the retained sentence "Hive never approves fork heads or PRs carrying sentinel-alert." That was true of the /ok-to-test path, but the new sweep does approve fork heads: workflowRunApprovable (workflow_auto_approval.go:239-247) only requires the run's head repository to equal the PR's head repository, and the trust comment at :186-193 explicitly states the policy is to approve fork pull_request runs when the author/actor is trusted or the head is admitted. TestSweepWorkflowApprovalsGuards only rejects a mismatched head repo (other/repo), not a fork. Either the sentence should be rewritten to describe the new fork policy, or a fork guard should be added — the owner should pick which, since that is the trust decision.

Why this needs the owner, not me

The PR body itself says the default-on question "was raised for owner sign-off on #16681 and still applies here". The change (a) raises the App's required permission from Actions: Read to Read and write in github-app-setup.md:32,46,…, and (b) enables, by default on upgrade, an App-token write that starts CI on fork-contributed code when the author is in the allowlist or the head was admitted from the dashboard. Both are permission/trust policy. I have not approved or requested changes; the decision question above is the one sentence to answer.

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

Code reads correct to me; routing for a permissions decision, not a defect.

What I verified on 2b258e6 (read the tree, not just the diff):

  • Once-per-head invariant lives in workflowApprovalLedger.claim (src/pkg/github/workflow_auto_approval.go:134-145) and is taken before the first POST; TestSweepWorkflowApprovalsConcurrentPassesApproveOnce covers the race.
  • The PR is re-read with PullRequests.Get and head/state/draft/labels re-checked before any write (workflow_auto_approval.go:333-345); the second splitTrustedWorkflowRuns uses the fresh author and head repo, not the cached listing.
  • Only event == "pull_request" runs are approvable (workflowRunApprovable, :230); pull_request_target is never approved. The shared probe workflowRunsAwaitingApproval is untouched, so the ✨ Activity Monitor chevrons: active-with-text / icon-only spec, CI and review ring glyph, workflow-approval stall caption #16599 caption still counts every gated run (TestWorkflowApprovalProbeCountsEveryEvent).
  • Admission is head-bound via stagelabels.Record.Admission(head) (src/pkg/stagelabels/store.go:1757); the automerge label alone is not trusted. TestSweepWorkflowApprovalsAdmissionIsHeadBound pins it.
  • A 403/404 is recorded once and workflowApprovalWithLedger carries PermissionDenied onto later cycles' probes (:171-187), so the caption survives cycles that skip the sweep. Helpers referenced (forgetWorkflowApproval, cloneCIActivity, labelNames, AppBotLogin) all exist at the cited call sites.
  • Sweep is gated on !budgetDecision.SkipOptional in src/cmd/hive/main_eval_cycle.go:588, matching what runtime-and-quota.md says.

Already decided, not re-asked: per #16603 (owner-authored) the default is auto_approve_workflows: true with dependabot[bot]/renovate[bot] as default actors; the diff implements exactly that, and hive.yaml.example:416-423 plus github-app-setup.md document the opt-out.

The one thing only a human can do: this PR changes the documented App requirement from Actions: Read to Actions: Read and write (src/docs/github-app-setup.md:43,93). Until that grant is made on each installation, the default-on sweep degrades to a logged permission_error per head — visible, bounded, but a behaviour change at merge time. Either grant it first, or ship with governor.ci.auto_approve_workflows: false in deployed configs.

No findings beyond that. I have not approved or changed anything.

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

docs-currency (delta re-review at 2b258e6)

Fixed since aa82bc7: src/docs/github-app-setup.md:46 no longer says Hive never approves fork heads, and src/docs/operator-reference/README.md:437-448 now names the gated-run approval sweep beside the registry-trusted lane.

Still present (in-scope): src/docs/hive-merge.md:789-791 still reads "the hive otherwise never approves a human-authored lane's held runs (the hive-ok-to-test workflow approves same-repo heads only)". With governor.ci.auto_approve_workflows default on, the sweep approves any head — human-authored included — that a verified owner or merger admitted from the dashboard (runtime-and-quota.md:275-285, github-app-setup.md:46). Suggested rewording: "…and, outside the gated-run approval sweep's owner/merger admission (governor.ci.auto_approve_workflows), the hive otherwise never approves a human-authored lane's held runs…".

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 5, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

docs-currency — read at head 9e1821e.

1. docs/github-app-setup.md and docs/acmm-policy-matrix.md now contradict the default-on behavior this PR ships (in-scope, medium).
docs/github-app-setup.md:46 still states "Hive does not require Actions: Read and write for bot workflow-run approvals; Actions: Read is enough to inspect runs. The one direct approval Hive performs — [registry-trusted contributor lane] — does need Read and write", the permission matrix at :43 lists Actions Read | Read | Read for every level, and :93 says "If GitHub holds trusted Dependabot/App/clanker runs in action_required, Hive posts /ok-to-test". docs/acmm-policy-matrix.md:195-203 has a whole section titled "Workflow approval, not App Actions-write permission" asserting "the App needs no Actions-write grant" for exactly the dependabot/App actors this PR targets.

With this PR, SweepWorkflowApprovals (src/pkg/github/workflow_auto_approval.go:245-342) POSTs /actions/runs/{id}/approve with the App token by default (AutoApproveWorkflowsEnabled is nil-true, src/pkg/config/governor_ci.go:22-24) for those same actors, and on 403/404 records permission_error and flips the CI caption to "CI waiting · needs workflow approval on GitHub … the App lacks the actions: write permission" (src/pkg/dashboard/stage_tracker_activity.go:284-288). An operator who followed github-app-setup.md as written (Actions: Read, relying on the hive-ok-to-test workflow, which automerge_held_runs.go:124 "never approves a run with the App token") will on upgrade see permission_errors climb and a caption telling them to click Approve, while the existing /ok-to-test path is concurrently handling the same head. None of the new text (runtime-and-quota.md:265-301, webhooks.md:117-118) mentions /ok-to-test or github-app-setup.md.

Requested change: (a) in docs/github-app-setup.md:43/46/93 state that the default-on governor.ci.auto_approve_workflows sweep requires Actions: Read and write, and that operators keeping Actions at Read should set it to false (or accept the permanent permission_errors / caption); (b) retitle/reword docs/acmm-policy-matrix.md:195-203 so it no longer claims the App needs no Actions-write grant for dependabot/App runs; (c) add one sentence to runtime-and-quota.md ~line 292 saying how this sweep relates to the existing /ok-to-test path (which runs first / which one an operator should expect to act).

Everything else I checked lines up with the code: lgtm default (client.go:1485), ci_rerun kind (writeback/kinds.go:86), optional_sweep_every_n_cycles and cached-snapshot SkipOptional (main_eval_cycle.go:509-517), log/caption strings, the /api/status field shape, and the settings-parity allowlist.

— hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

The sweep trusted a PR for the automerge label alone, which is bound to
no head and names no approver. Read the stage record's head-bound
admission (dashboard Approve by a verified owner or merger, #15136)
instead; a label on its own never approves a run. Move the ledger
mutations into markDeniedCounted/claim so the once-per-head invariant
lives on the ledger type. Document that the default-on sweep needs the
App's Actions: Read and write and how it relates to /ok-to-test.

Hive-Fix-Attempt: 1/6
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 5, 2026
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Nov 5, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Read at head f868e0a against v5. The docs-currency change requested at 9e1821e is addressed, and the trust-policy rework since that head checks out. Looks correct to me.

What I verified

  • Owner admission is now head-bound. src/pkg/github/workflow_auto_approval.go:246-256 reads stagelabels.Record.Admission(head), which returns "" unless AdmittedHead == head (src/pkg/stagelabels/store.go:1757-1763). The only writers are the dashboard Approve (src/pkg/dashboard/api_repo_item_decision.go:211) and the contributor lane after a trusted-merger approval is recorded (src/pkg/github/automerge/automerge_operator_admission.go:52), so a contributor cannot carry an admission onto a later push. This is tighter than #16603's "carries the owner's lgtm admission" wording — a deliberate and sound narrowing, and runtime-and-quota.md / webhooks.md now say so.
  • Event and head-repo filter sit in the approval decision, not the probe. workflowRunApprovable (workflow_auto_approval.go:215-231) admits only pull_request runs on the exact head SHA and, once the fresh PR read supplies it, the matching head repository; workflowApprovalFromRuns (workflow_approval.go:119) is unchanged apart from retaining runs, so the #16599 caption still counts every gated run.
  • Once-per-head holds under concurrency. claim (:124-135) flips attempted under the ledger mutex before the first POST; a partial failure does not reopen the head. touchLocked (:86-104) evicts superseded heads and >24h entries, so the ledger stays bounded.
  • Default-on + Actions: write is stated as such in #16603 (per #16603: governor.ci.auto_approve_workflows default true, 403 recorded once and surfaced in the caption), and github-app-setup.md:43/46/93 and acmm-policy-matrix.md:196-208 now document the grant and the false escape hatch.

Open question for the owner, not blocking: GitHub treats 404 as the "no actions: write" signal here (:349) — a run that was approved or cancelled between the listing and the POST would also be recorded as permission_error and flip the caption for that head. Rare, and the next push clears it.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot added stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 5, 2026
Document why trusting the App as a run's triggering actor cannot approve
contributor code: GitHub gates only fork pull_request runs and the App
cannot push to a fork, so an App-pushed same-repository branch is never
gated. Code comment on workflowApprovalTrusted and the operator reference.

The default of governor.ci.auto_approve_workflows stays as #16603
specifies (on); flipping it is the owner's call, not a code defect.

Hive-Fix-Attempt: 2/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Nov 5, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

security · delta re-review at aa82bc7 (previous head f868e0a)

Delta is comment/doc text only (src/pkg/github/workflow_auto_approval.go:186-193, src/docs/operator-reference/runtime-and-quota.md:280-285); no behavior change.

Prior findings:

  • App as triggering actor trusts the run on contributor code — resolved: the new comment states the argument and I checked it against the code. workflowRunApprovable (workflow_auto_approval.go:217-219) approves only pull_request runs matching the PR head and head repo; GitHub gates only fork pull_request runs, and an installation token scoped to the base repo cannot push to a fork, so a fork head's triggering_actor is the fork pusher, not the App. The fresh PR re-read before the POST (:323-326) re-binds author/head.
  • governor.ci.auto_approve_workflows default-on — still present, no longer blocking: #16603 specifies default true and App trust verbatim; the PR body flags the default for owner sign-off and the operator reference documents false for self-hosted runners.

Advisory (non-blocking): the fork-safety argument assumes the login returned by AppBotLogin() (workflow_auto_approval.go:271) is pushable only by this hive. If the GitHub App is public and a contributor installs it on their fork, pushes from that installation carry the same <slug>[bot] login and would be trusted as "the App" on a fork head. Worth a sentence in the comment ("the App is private to the owner") or a headRepo == base repo check in the actor branch; not required for #16603.

— hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot added stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 5, 2026
@clubanderson

Copy link
Copy Markdown
Member

Owner decision (@clubanderson): approved as written.

  • governor.ci.auto_approve_workflows default-on stands. The covered actors (dependabot/renovate, the hive's own App, heads an owner admitted with lgtm) are exactly the ones where the Approve click adds no information. Self-hosted operators set it to false; the operator reference says so.
  • actions: write on the App is accepted; it is the minimum for this feature.
  • Approving dashboard/lgtm-admitted fork heads is consistent with what lgtm already means (a maintainer read the head).
  • pull_request_target runs are never approved, which is the case that matters.

Reviewer cleared correctness; CI is green on d18fb6c. Merging.

/approve
/lgtm

@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: clubanderson

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

The pull request process is described 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

Copy link
Copy Markdown
Contributor

LGTM label has been added.

DetailsGit tree hash: 80e390b8091c1e9c7a1da095fd90afc935c29cd2

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue

Projects

None yet

1 participant