From 1681836fbd8be5f0e9f3907d66d43be5f7ca0202 Mon Sep 17 00:00:00 2001 From: Danathar Date: Sat, 7 Nov 2026 21:03:33 -0500 Subject: [PATCH 1/4] fix(automerge): approve a contributor's held runs once per head, not once per sweep The contributor lane's once-per-head mark for held-run approvals lived on the automerge engine, which SweepContributorLaneAutoMerges rebuilds every tick. A head whose approvals GitHub refused with 403 (App without actions: write) was therefore re-POSTed on every sweep: on projectbluefin dakota-iso#307 and fsdk-containers#508 cost ~270 charged POST actions/runs/{id}/approve calls an hour, all 403. Move the pass and the refusal into a process-wide ledger on the GitHub client (HeldRunApprovals). A refused head keeps reporting unauthorized:approve-workflow-runs without another call until the head changes or the installation gains actions: write (read via InstallationPermission, cached 5 min). Only send runs GitHub's approve endpoint accepts: fork pull_request runs and Actions-bot runs. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar --- changelog.d/fixed-held-run-approve-once.md | 1 + src/docs/hive-merge.md | 15 +- src/docs/operator-reference/README.md | 2 +- .../automerge_contributor_held_runs.go | 92 +++++--- ...merge_contributor_held_runs_ledger_test.go | 213 ++++++++++++++++++ .../automerge_contributor_held_runs_test.go | 44 ++-- .../automerge/automerge_held_runs_test.go | 2 +- src/pkg/github/automerge/automerge_sweep.go | 33 +++ src/pkg/github/client.go | 2 + src/pkg/github/held_run_approvals.go | 197 ++++++++++++++++ src/pkg/github/held_run_approvals_test.go | 118 ++++++++++ 11 files changed, 668 insertions(+), 51 deletions(-) create mode 100644 changelog.d/fixed-held-run-approve-once.md create mode 100644 src/pkg/github/automerge/automerge_contributor_held_runs_ledger_test.go create mode 100644 src/pkg/github/held_run_approvals.go create mode 100644 src/pkg/github/held_run_approvals_test.go diff --git a/changelog.d/fixed-held-run-approve-once.md b/changelog.d/fixed-held-run-approve-once.md new file mode 100644 index 0000000000..a006f5682d --- /dev/null +++ b/changelog.d/fixed-held-run-approve-once.md @@ -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. diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index 4884447923..2cd683aab0 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -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:`, 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 `` 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 `` 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), 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 diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 31d34753fe..18b680f271 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -545,7 +545,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:` (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:` (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). | diff --git a/src/pkg/github/automerge/automerge_contributor_held_runs.go b/src/pkg/github/automerge/automerge_contributor_held_runs.go index 37659244cf..05d81ab8b9 100644 --- a/src/pkg/github/automerge/automerge_contributor_held_runs.go +++ b/src/pkg/github/automerge/automerge_contributor_held_runs.go @@ -57,6 +57,12 @@ const ( // for this head (hivecommons/hive#14589) — GitHub answers 403 "Resource not // accessible by integration", the PR is marked via markUnauthorized, and the // mark holds until the head's required checks exist or the head changes. +// The pass and any refusal live in the process-wide hgithub.HeldRunApprovals +// ledger, not on the engine: the sweep builds a new engine every tick, and +// an engine-local map let a refused head be re-POSTed on every sweep. A +// refused head is not tried again until it changes or the App gains +// `actions: write`. Held runs GitHub's approve endpoint never accepts +// (approvableHeldRun) are not sent at all. func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayRepo, owner, repo string, pr *gh.PullRequest, number int, headSHA string, claim contributorClaimMatch, policy ContributorLanePolicy, files []intent.ChangedFile, reason string) ([]int64, string) { if c == nil || c.gh == nil || pr == nil || headSHA == "" { return nil, reason @@ -74,12 +80,18 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR if contributorLaneDiffReason(files) == contributorLaneReasonWorkflowPath { return nil, reason } - if c.contributorHeldRunsApprovalAttempted(owner, repo, number, headSHA) { - // Already tried this head; keep reporting the permission gap while - // it stands, without another API call or another log line. - if step := c.unauthorizedStep(owner, repo, number, headSHA); step == unauthorizedStepApproveWorkflowRuns { - return nil, unauthorizedReason(step) + fullRepo := owner + "/" + repo + if refused, ok := c.heldRuns.Refused(fullRepo, number, headSHA); ok { + // GitHub refused this head's approvals before. Keep reporting the + // blocker without another POST: the refusal stands until the head + // changes or the App gains `actions: write`. + level, known := c.actionsPermission(ctx) + if !c.heldRuns.ReleaseOnGrant(fullRepo, number, headSHA, level, known) { + return nil, unauthorizedReason(unauthorizedStepApproveWorkflowRuns) } + c.info("contributor-lane retrying held-run approval: the App now holds actions: write", "repo", displayRepo, "pr", number, "head", headSHA, "refused_runs", refused) + } else if c.heldRuns.Attempted(fullRepo, number, headSHA) { + // Already approved (or tried to) on this head. return nil, reason } missing := "" @@ -105,9 +117,17 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR // evidence gap is not the approval hold, so leave it alone. return nil, reason } - // Mark before calling the API: a partial failure must not be retried - // every tick against the same head. - if !c.markContributorHeldRunsApprovalAttempted(owner, repo, number, headSHA) { + // GitHub approves only fork pull_request runs (or runs the Actions bot + // queued); any other held run answers 403 on every try, so it is never + // sent. Those runs stay a person's click on the checks banner. + held = approvableHeldRuns(held, fullRepo) + if len(held) == 0 { + return nil, reason + } + // Claim before calling the API: a partial failure must not be retried + // every tick against the same head. The ledger is process-wide, so the + // claim holds across the sweep's one-shot engines. + if !c.heldRuns.Claim(fullRepo, number, headSHA) { return nil, reason } author := hgithub.SafeGetLogin(pr.GetUser()) @@ -125,6 +145,8 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR } if len(forbidden) > 0 && len(approved) == 0 { sort.Slice(forbidden, func(i, j int) bool { return forbidden[i] < forbidden[j] }) + level, known := c.actionsPermission(ctx) + c.heldRuns.RecordRefusal(fullRepo, number, headSHA, forbidden, level, known) return nil, c.markUnauthorized(ctx, displayRepo, owner, repo, pr, number, headSHA, unauthorizedStepApproveWorkflowRuns, unauthorizedPermissionActionsWrite, approveWorkflowRunsHumanAction(owner, repo, missing, forbidden)) } if len(approved) == 0 { @@ -196,32 +218,44 @@ func heldWorkflowRunsForHead(runs []*gh.WorkflowRun, headRepo string) []*gh.Work return held } -func contributorHeldRunsApprovalKey(prKey, headSHA string) string { - return contributorHeldRunsApprovalKeyPrefix + prKey + "@" + strings.ToLower(headSHA) -} - -// contributorHeldRunsApprovalAttempted reports whether this process already -// approved (or tried to approve) the held runs for this PR head. -func (c *Engine) contributorHeldRunsApprovalAttempted(owner, repo string, number int, headSHA string) bool { - c.heldRunApprovalsMu.Lock() - defer c.heldRunApprovalsMu.Unlock() - return c.heldRunApprovals[contributorHeldRunsApprovalKey(c.evaluatedHeadKey(owner, repo, number), headSHA)] +// approvableHeldRuns keeps the held runs GitHub's approve endpoint +// accepts: a `pull_request` run whose head repository is a fork of +// baseRepo, or a run the Actions bot queued. GitHub answers any other run +// with 403 "This run is not from a fork pull request or queued by the +// Actions bot", forever. The fork test compares repositories rather than +// reading head_repository.fork, which is true for any repository that is +// itself a fork (projectbluefin/dakota-iso is). +func approvableHeldRuns(runs []*gh.WorkflowRun, baseRepo string) []*gh.WorkflowRun { + var out []*gh.WorkflowRun + for _, run := range runs { + if approvableHeldRun(run, baseRepo) { + out = append(out, run) + } + } + return out } -// markContributorHeldRunsApprovalAttempted records the attempt for this PR -// head and reports whether it is the first. -func (c *Engine) markContributorHeldRunsApprovalAttempted(owner, repo string, number int, headSHA string) bool { - key := contributorHeldRunsApprovalKey(c.evaluatedHeadKey(owner, repo, number), headSHA) - c.heldRunApprovalsMu.Lock() - defer c.heldRunApprovalsMu.Unlock() - if c.heldRunApprovals == nil { - c.heldRunApprovals = make(map[string]bool) +func approvableHeldRun(run *gh.WorkflowRun, baseRepo string) bool { + if run == nil || run.GetID() <= 0 { + return false } - if c.heldRunApprovals[key] { + if strings.EqualFold(run.GetTriggeringActor().GetLogin(), githubActionsBotLogin) { + return true + } + if run.GetEvent() != "pull_request" { return false } - c.heldRunApprovals[key] = true - return true + head := strings.TrimSpace(run.GetHeadRepository().GetFullName()) + return head != "" && !strings.EqualFold(head, baseRepo) +} + +// actionsPermission reads the App installation's `actions` grant; known +// is false when the transport cannot read it. +func (c *Engine) actionsPermission(ctx context.Context) (string, bool) { + if c == nil || c.installationPermission == nil { + return "", false + } + return c.installationPermission(ctx, "actions") } // contributorHeldRunsApprovedComment is the audit comment body; the marker diff --git a/src/pkg/github/automerge/automerge_contributor_held_runs_ledger_test.go b/src/pkg/github/automerge/automerge_contributor_held_runs_ledger_test.go new file mode 100644 index 0000000000..81aa8a1939 --- /dev/null +++ b/src/pkg/github/automerge/automerge_contributor_held_runs_ledger_test.go @@ -0,0 +1,213 @@ +package automerge + +// The contributor lane's held-run approvals across sweeps. Production runs +// SweepContributorLaneAutoMerges, which builds a new Engine every tick +// (New(transport, opts)), so these tests build one engine per tick on one +// shared transport, as the hive does. projectbluefin, 2026-11-08 00:40-01:44Z: +// dakota-iso#307 and fsdk-containers#508 each had 3 held fork runs and the +// App lacks `actions: write`; every sweep re-POSTed all 6 and got 403. + +import ( + "context" + "net/http" + "slices" + "strings" + "testing" + "time" + + gh "github.com/google/go-github/v72/github" + hgithub "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// contributorLaneTickEngines returns a constructor for one engine per +// sweep tick, all sharing one transport and one set of trackers. +func contributorLaneTickEngines(apiURL string, policy ContributorLanePolicy, clock *contributorLaneClock, opts Options) func() *Engine { + client := hgithub.NewClient("token", "acme", []string{"widget"}, nil, apiURL) + client.SetAppBotLogin(testHiveAppBotLogin) + opts.ContributorLanePolicy = func() ContributorLanePolicy { return policy } + opts.BasePreparation = NewBasePreparationStore("") + opts.ContributorLaneVerdict = approvedVerdict + if opts.ContributorSoak == nil { + opts.ContributorSoak = soakedTracker(clock) + } + opts.HeadFirstSeen = NewHeadFirstSeenTracker() + opts.StageStore = stagelabels.NewStore("", nil) + opts.Now = clock.now + opts.SentinelLabel = func() string { return "hive-sentinel" } + return func() *Engine { return New(client, opts) } +} + +func contributorHeldRunsLanePolicy() ContributorLanePolicy { + policy := defaultContributorLanePolicy() + policy.RegistryTiersSufficient = true + policy.ApproveHeldRunsForRegistryTrusted = true + return policy +} + +func contributorHeldRunsForkFixture() contributorLaneFixture { + fx := validContributorFixture() + fx.baseRef = "main" + fx.body = "Part of #42\n\nSome change." + fx.issueComments = nil + fx.requiredContexts = []string{"ci/build", contributorHeldRunsTestContext} + fx.headRepo = contributorHeldRunsTestFork + fx.workflowRuns = []map[string]any{heldRun(11, contributorHeldRunsTestFork), heldRun(12, contributorHeldRunsTestFork)} + return fx +} + +// A refused approval is not re-POSTed by the next sweep's engine; the PR +// keeps reporting the blocker, with one note and one label. +func TestContributorLaneRefusedHeldRunsNotRetriedAcrossSweeps(t *testing.T) { + fx := contributorHeldRunsForkFixture() + fx.approveStatus = http.StatusForbidden + api := newContributorLaneAPI(t, &fx) + defer api.Close() + policy := contributorHeldRunsLanePolicy() + clock := &contributorLaneClock{at: time.Date(2026, 11, 8, 1, 0, 0, 0, time.UTC)} + tick := contributorLaneTickEngines(api.URL, policy, clock, Options{ContributorRegistryTier: registryTiers(map[string]string{contributorLaneTestAuthor: "trusted"})}) + + wantReason := unauthorizedReason(unauthorizedStepApproveWorkflowRuns) + for i := 1; i <= 4; i++ { + _, reason, err := tick().trySweepContributorLanePR(context.Background(), "widget", "acme", "widget", 7, policy) + if err != nil { + t.Fatalf("sweep %d err = %v", i, err) + } + if reason != wantReason { + t.Fatalf("sweep %d reason = %q, want %q", i, reason, wantReason) + } + } + if !slices.Equal(fx.approvedRuns, []int64{11, 12}) { + t.Fatalf("approve POSTs = %v, want [11 12] once across 4 sweeps", fx.approvedRuns) + } + if fx.comments != 1 || len(fx.labelsAdded) != 1 { + t.Fatalf("comments = %d labels added = %v, want one unauthorized note and one label", fx.comments, fx.labelsAdded) + } + if !slices.Contains(fx.labels, unauthorizedLabel) || len(fx.labelsRemoved) != 0 { + t.Fatalf("labels = %v removed = %v, want %q kept while the runs are held", fx.labels, fx.labelsRemoved, unauthorizedLabel) + } +} + +// A refused head is tried again when the App gains `actions: write`, and +// any new head gets its own pass; a fork pull_request run on a new head is +// approved once GitHub accepts it. +func TestContributorLaneRefusedHeldRunsRetryOnGrantOrNewHead(t *testing.T) { + fx := contributorHeldRunsForkFixture() + fx.approveStatus = http.StatusForbidden + api := newContributorLaneAPI(t, &fx) + defer api.Close() + policy := contributorHeldRunsLanePolicy() + clock := &contributorLaneClock{at: time.Date(2026, 11, 8, 1, 0, 0, 0, time.UTC)} + grant := "read" + tick := contributorLaneTickEngines(api.URL, policy, clock, Options{ + ContributorRegistryTier: registryTiers(map[string]string{contributorLaneTestAuthor: "trusted"}), + InstallationPermission: func(_ context.Context, name string) (string, bool) { + if name != "actions" { + t.Fatalf("permission read = %q, want actions", name) + } + return grant, true + }, + }) + pr := &gh.PullRequest{ + Number: gh.Ptr(7), + User: &gh.User{Login: gh.Ptr(contributorLaneTestAuthor)}, + Head: &gh.PullRequestBranch{Repo: &gh.Repository{FullName: gh.Ptr(contributorHeldRunsTestFork)}}, + } + claim := contributorClaimMatch{RegistryTier: "trusted"} + missing := requiredCheckMissingPrefix + contributorHeldRunsTestContext + unauthorized := unauthorizedReason(unauthorizedStepApproveWorkflowRuns) + pass := func(step, head string, wantPOSTs int, wantReason string) []int64 { + t.Helper() + approved, reason := tick().approveHeldRunsForRegistryTrusted(context.Background(), "widget", "acme", "widget", pr, 7, head, claim, policy, nil, missing) + if reason != wantReason { + t.Fatalf("%s: reason = %q, want %q", step, reason, wantReason) + } + if len(fx.approvedRuns) != wantPOSTs { + t.Fatalf("%s: approve POSTs = %v, want %d in total", step, fx.approvedRuns, wantPOSTs) + } + return approved + } + + pass("first refusal", "sha7", 2, unauthorized) + pass("same head, same grant", "sha7", 2, unauthorized) + grant = "write" + pass("grant gained", "sha7", 4, unauthorized) + pass("refused again holding write", "sha7", 4, unauthorized) + pass("new head", "sha8", 6, unauthorized) + pass("new head, no retry", "sha8", 6, unauthorized) + + fx.approveStatus = 0 + if approved := pass("another head GitHub accepts", "sha9", 8, missing); !slices.Equal(approved, []int64{11, 12}) { + t.Fatalf("approved = %v, want [11 12]", approved) + } + pass("accepted head, no second pass", "sha9", 8, missing) +} + +// Only runs GitHub's approve endpoint accepts are sent: a fork +// pull_request run or one the Actions bot queued. A pull_request_review +// run (projectbluefin/dakota-iso run 42341060495) or a pull_request_target +// run on the same fork head is never approved, even when the listing +// returns it. +func TestContributorLaneApprovesOnlyForkPullRequestHeldRuns(t *testing.T) { + fx := contributorHeldRunsForkFixture() + withEvent := func(run map[string]any, event string) map[string]any { + run["event"] = event + return run + } + actionsBot := heldRun(24, contributorHeldRunsTestFork) + actionsBot["event"] = "workflow_run" + actionsBot["triggering_actor"] = map[string]any{"login": githubActionsBotLogin} + fx.workflowRuns = []map[string]any{ + heldRun(11, contributorHeldRunsTestFork), + withEvent(heldRun(21, contributorHeldRunsTestFork), "pull_request_review"), + withEvent(heldRun(22, contributorHeldRunsTestFork), "pull_request_target"), + actionsBot, + } + api := newContributorLaneAPI(t, &fx) + defer api.Close() + policy := contributorHeldRunsLanePolicy() + clock := &contributorLaneClock{at: time.Date(2026, 11, 8, 1, 0, 0, 0, time.UTC)} + tick := contributorLaneTickEngines(api.URL, policy, clock, Options{ContributorRegistryTier: registryTiers(map[string]string{contributorLaneTestAuthor: "trusted"})}) + + for i := 1; i <= 2; i++ { + if _, _, err := tick().trySweepContributorLanePR(context.Background(), "widget", "acme", "widget", 7, policy); err != nil { + t.Fatalf("sweep %d err = %v", i, err) + } + } + if !slices.Equal(fx.approvedRuns, []int64{11, 24}) { + t.Fatalf("approve POSTs = %v, want [11 24]: the fork pull_request run and the Actions-bot run, once", fx.approvedRuns) + } + if !strings.Contains(fx.lastComment, "runs=11,24") { + t.Fatalf("audit comment = %q, want it to name runs 11 and 24", fx.lastComment) + } +} + +func TestApprovableHeldRun(t *testing.T) { + run := func(event, headRepo, actor string) *gh.WorkflowRun { + r := &gh.WorkflowRun{ID: gh.Ptr(int64(1)), Event: gh.Ptr(event), HeadRepository: &gh.Repository{FullName: gh.Ptr(headRepo)}} + if actor != "" { + r.TriggeringActor = &gh.User{Login: gh.Ptr(actor)} + } + return r + } + for _, tc := range []struct { + name string + run *gh.WorkflowRun + want bool + }{ + {"fork pull_request", run("pull_request", "kyle/widget", "kyle"), true}, + {"fork pull_request, owner case differs", run("pull_request", "Kyle/Widget", ""), true}, + {"same-repo pull_request", run("pull_request", "Acme/Widget", "kyle"), false}, + {"pull_request_review on the base (dakota-iso run 42341060495)", run("pull_request_review", "acme/widget", "hivecommons-hive[bot]"), false}, + {"pull_request_review on the fork", run("pull_request_review", "kyle/widget", "kyle"), false}, + {"pull_request_target", run("pull_request_target", "kyle/widget", "kyle"), false}, + {"queued by the Actions bot", run("push", "acme/widget", githubActionsBotLogin), true}, + {"no head repository", run("pull_request", "", "kyle"), false}, + {"nil", nil, false}, + {"no id", &gh.WorkflowRun{Event: gh.Ptr("pull_request"), HeadRepository: &gh.Repository{FullName: gh.Ptr("kyle/widget")}}, false}, + } { + if got := approvableHeldRun(tc.run, "acme/widget"); got != tc.want { + t.Errorf("%s: approvableHeldRun = %v, want %v", tc.name, got, tc.want) + } + } +} diff --git a/src/pkg/github/automerge/automerge_contributor_held_runs_test.go b/src/pkg/github/automerge/automerge_contributor_held_runs_test.go index a8726af404..3d1da50334 100644 --- a/src/pkg/github/automerge/automerge_contributor_held_runs_test.go +++ b/src/pkg/github/automerge/automerge_contributor_held_runs_test.go @@ -22,6 +22,10 @@ import ( const contributorHeldRunsTestContext = "Audit production dependencies" +// contributorHeldRunsTestFork is the fork a contributor PR's head lives in: +// GitHub approves held runs only for fork pull_request heads. +const contributorHeldRunsTestFork = "kyle/widget" + func TestContributorLaneApprovesHeldRunsForRegistryTrusted(t *testing.T) { registryTrusted := registryTiers(map[string]string{contributorLaneTestAuthor: "trusted"}) noMarker := func(fx *contributorLaneFixture) { @@ -54,12 +58,12 @@ func TestContributorLaneApprovesHeldRunsForRegistryTrusted(t *testing.T) { wantComments: 1, }, { - name: "registry trusted same-repo head approves once", - registry: registryTrusted, - mutate: noMarker, - wantReason: wantReason, - wantApproved: []int64{11, 12}, - wantComments: 1, + // GitHub answers 403 "not from a fork pull request" for a + // same-repo run, on every try: the lane never sends it. + name: "registry trusted same-repo head is not approved", + registry: registryTrusted, + mutate: noMarker, + wantReason: wantReason, }, { name: "auto-promoted author is not approved for", @@ -114,9 +118,13 @@ func TestContributorLaneApprovesHeldRunsForRegistryTrusted(t *testing.T) { { // A non-403 approve failure is logged and otherwise changes nothing // (the unauthorized path is TestContributorLaneUnauthorizedWhenApproveForbidden). - name: "approve server error posts no comment and sets no label", - registry: registryTrusted, - mutate: func(fx *contributorLaneFixture) { noMarker(fx); fx.approveStatus = http.StatusInternalServerError }, + name: "approve server error posts no comment and sets no label", + registry: registryTrusted, + mutate: func(fx *contributorLaneFixture) { + noMarker(fx) + fx.headRepo = contributorHeldRunsTestFork + fx.approveStatus = http.StatusInternalServerError + }, wantReason: wantReason, wantApproved: []int64{11, 12}, }, @@ -194,7 +202,8 @@ func TestContributorLaneHeldRunsApprovalCommentIsIdempotent(t *testing.T) { fx.body = "Part of #42\n\nSome change." fx.issueComments = nil fx.requiredContexts = []string{"ci/build", contributorHeldRunsTestContext} - fx.workflowRuns = []map[string]any{heldRun(11, "acme/widget")} + fx.headRepo = contributorHeldRunsTestFork + fx.workflowRuns = []map[string]any{heldRun(11, contributorHeldRunsTestFork)} fx.prComments = []map[string]any{{ "id": 5, "user": map[string]string{"login": testHiveAppBotLogin}, @@ -282,7 +291,8 @@ func TestContributorLaneUnauthorizedWhenApproveForbidden(t *testing.T) { fx.body = "Part of #42\n\nSome change." fx.issueComments = nil fx.requiredContexts = []string{"ci/build", contributorHeldRunsTestContext} - fx.workflowRuns = []map[string]any{heldRun(11, "acme/widget"), heldRun(12, "acme/widget")} + fx.headRepo = contributorHeldRunsTestFork + fx.workflowRuns = []map[string]any{heldRun(11, contributorHeldRunsTestFork), heldRun(12, contributorHeldRunsTestFork)} fx.approveStatus = http.StatusForbidden if tc.labelled { fx.labels = []string{unauthorizedLabel} @@ -377,7 +387,8 @@ func TestContributorLaneConflictClearsUnauthorized(t *testing.T) { fx.body = "Part of #42\n\nSome change." fx.issueComments = nil fx.requiredContexts = []string{"ci/build", contributorHeldRunsTestContext} - fx.workflowRuns = []map[string]any{heldRun(11, "acme/widget")} + fx.headRepo = contributorHeldRunsTestFork + fx.workflowRuns = []map[string]any{heldRun(11, contributorHeldRunsTestFork)} fx.approveStatus = http.StatusForbidden api := newContributorLaneAPI(t, &fx) defer api.Close() @@ -511,21 +522,21 @@ func TestContributorLaneApprovesHeldRunsWhenCIUnverifiedAndAllHeld(t *testing.T) }{ { name: "every run held approves", - runs: []map[string]any{heldRun(11, "acme/widget"), heldRun(12, "acme/widget"), heldRun(14, "mallory/widget")}, + runs: []map[string]any{heldRun(11, contributorHeldRunsTestFork), heldRun(12, contributorHeldRunsTestFork), heldRun(14, "mallory/widget")}, registry: map[string]string{contributorLaneTestAuthor: "trusted"}, wantApproved: []int64{11, 12}, }, { name: "a run already in progress leaves it alone", runs: []map[string]any{ - heldRun(11, "acme/widget"), - {"id": 13, "name": "lint", "status": "in_progress", "head_repository": map[string]any{"full_name": "acme/widget"}}, + heldRun(11, contributorHeldRunsTestFork), + {"id": 13, "name": "lint", "event": "pull_request", "status": "in_progress", "head_repository": map[string]any{"full_name": contributorHeldRunsTestFork}}, }, registry: map[string]string{contributorLaneTestAuthor: "trusted"}, }, { name: "claim marker author is not approved for", - runs: []map[string]any{heldRun(11, "acme/widget")}, + runs: []map[string]any{heldRun(11, contributorHeldRunsTestFork)}, registry: nil, }, } { @@ -537,6 +548,7 @@ func TestContributorLaneApprovesHeldRunsWhenCIUnverifiedAndAllHeld(t *testing.T) fx.issueComments = nil } fx.noCIEvidence = true + fx.headRepo = contributorHeldRunsTestFork fx.workflowRuns = tc.runs api := newContributorLaneAPI(t, &fx) defer api.Close() diff --git a/src/pkg/github/automerge/automerge_held_runs_test.go b/src/pkg/github/automerge/automerge_held_runs_test.go index f2c695986f..c22f78b43c 100644 --- a/src/pkg/github/automerge/automerge_held_runs_test.go +++ b/src/pkg/github/automerge/automerge_held_runs_test.go @@ -23,7 +23,7 @@ import ( func heldRun(id int, headRepo string) map[string]any { return map[string]any{ - "id": id, "name": "v2 CI", "status": "completed", "conclusion": "action_required", + "id": id, "name": "v2 CI", "event": "pull_request", "status": "completed", "conclusion": "action_required", "head_repository": map[string]any{"full_name": headRepo}, } } diff --git a/src/pkg/github/automerge/automerge_sweep.go b/src/pkg/github/automerge/automerge_sweep.go index 8fddd76997..a0cf5888f8 100644 --- a/src/pkg/github/automerge/automerge_sweep.go +++ b/src/pkg/github/automerge/automerge_sweep.go @@ -201,6 +201,15 @@ type Options struct { // HeadFirstSeen overrides the process-wide head-age tracker. nil shares // the package default so one-shot engines keep a head's pinned age. HeadFirstSeen *HeadFirstSeenTracker + // HeldRunApprovals overrides where the contributor lane remembers its + // held-run approval passes. nil uses the transport's process-wide + // ledger (hgithub.Client.HeldRunApprovals) so a one-shot engine per + // tick does not re-POST a refused approval every sweep. + HeldRunApprovals *hgithub.HeldRunApprovals + // InstallationPermission overrides how the lane reads the App + // installation's grant for a permission (level, known). nil uses the + // transport's InstallationPermission when it has one. + InstallationPermission func(ctx context.Context, name string) (level string, known bool) // MergeQueueBases is the memory of base branches that refused a direct // merge as merge-queue-only. The hive passes one instance to every sweep // engine and to the merge-eligibility classifier, so a base one lane @@ -402,6 +411,11 @@ type Engine struct { // nudges and bot takeovers (historic name; workflow approvals no longer use it). heldRunApprovalsMu sync.Mutex heldRunApprovals map[string]bool + // heldRuns is the process-wide record of the contributor lane's + // held-run approval passes (Options.HeldRunApprovals); + // installationPermission reads the App's grants for its retry rule. + heldRuns *hgithub.HeldRunApprovals + installationPermission func(ctx context.Context, name string) (string, bool) // workflowApprovalCommands records the first time this process saw and // commented /ok-to-test for a PR head. The mutation boundary dedupes the // actual comment across restarts; this clock drives the missing-caller grace. @@ -559,6 +573,25 @@ func New(transport Transport, opts Options) *Engine { if e.headFirstSeen == nil { e.headFirstSeen = sharedHeadFirstSeen } + e.heldRuns = opts.HeldRunApprovals + if e.heldRuns == nil { + if provider, ok := transport.(interface { + HeldRunApprovals() *hgithub.HeldRunApprovals + }); ok { + e.heldRuns = provider.HeldRunApprovals() + } + } + if e.heldRuns == nil { + e.heldRuns = &hgithub.HeldRunApprovals{} + } + e.installationPermission = opts.InstallationPermission + if e.installationPermission == nil { + if provider, ok := transport.(interface { + InstallationPermission(ctx context.Context, name string) (string, bool) + }); ok { + e.installationPermission = provider.InstallationPermission + } + } if e.sweepTrigger == nil { // Always present: with the forgestate cache the event-driven loop // drains it; without, the legacy ticker loop still selects on it so diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 95dd99c15f..df4ef719fa 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -179,6 +179,8 @@ type Client struct { mergeAlertLastRevalidate time.Time logger *slog.Logger workflowApprovals workflowApprovalLedger + heldRunApprovals HeldRunApprovals + installationPerms installationPermissionCache mergedClaimScanTransient sync.Map // repo -> true while its merged-PR scan is timing out stageFacts stageFactsState // out-of-cycle stage writes; see StageFacts apiBudget apiBudgetState diff --git a/src/pkg/github/held_run_approvals.go b/src/pkg/github/held_run_approvals.go new file mode 100644 index 0000000000..4c20871a65 --- /dev/null +++ b/src/pkg/github/held_run_approvals.go @@ -0,0 +1,197 @@ +package github + +import ( + "context" + "strconv" + "strings" + "sync" + "time" +) + +// HeldRunApprovals is the process-wide record of the contributor lane's +// passes over GitHub's "approve and run workflows" gate: one entry per PR, +// for the head the lane last tried to approve runs on. +// +// It lives on the long-lived Client because the automerge sweeps run on a +// one-shot engine per tick (automerge.SweepContributorLaneAutoMerges): a +// once-per-head map on the engine was empty again on the next tick, so a +// head whose approvals GitHub refused with 403 was POSTed every sweep — +// 3 runs × 2 PRs every ~80 s on projectbluefin, ~270 charged calls an hour +// that could never succeed. +// +// A pass is taken once per head. A refusal is remembered with the runs +// GitHub refused and the App's `actions` permission at the time, so the +// lane keeps reporting the blocker without calling GitHub again until the +// head changes or the installation gains `actions: write`. +type HeldRunApprovals struct { + mu sync.Mutex + entries map[string]heldRunApprovalEntry +} + +type heldRunApprovalEntry struct { + head string + refused bool + refusedRuns []int64 + grant string + grantKnown bool + seen time.Time +} + +// heldRunApprovalTTL bounds the ledger: an entry no pass has touched for +// this long belongs to a merged, closed or superseded PR. +const heldRunApprovalTTL = 24 * time.Hour + +func heldRunApprovalKey(repo string, number int) string { + return strings.ToLower(strings.TrimSpace(repo)) + "#" + strconv.Itoa(number) +} + +// lookupLocked returns the PR's entry when it covers head. An entry for +// another head is left for the next write (Claim) to replace, so a read +// with a stale head never wipes the current one. +func (l *HeldRunApprovals) lookupLocked(key, head string, now time.Time) (heldRunApprovalEntry, bool) { + if l.entries == nil { + l.entries = map[string]heldRunApprovalEntry{} + } + for other, entry := range l.entries { + if now.Sub(entry.seen) >= heldRunApprovalTTL { + delete(l.entries, other) + } + } + entry, ok := l.entries[key] + if !ok { + return heldRunApprovalEntry{}, false + } + if !strings.EqualFold(entry.head, head) { + return heldRunApprovalEntry{}, false + } + entry.seen = now + l.entries[key] = entry + return entry, true +} + +// Attempted reports whether a pass already ran on this PR head. +func (l *HeldRunApprovals) Attempted(repo string, number int, head string) bool { + if l == nil { + return false + } + l.mu.Lock() + defer l.mu.Unlock() + _, ok := l.lookupLocked(heldRunApprovalKey(repo, number), head, time.Now()) + return ok +} + +// Claim takes the head's one pass and reports whether it is the first. A +// new head replaces the PR's entry, so a push re-arms the pass. +func (l *HeldRunApprovals) Claim(repo string, number int, head string) bool { + if l == nil { + return true + } + now := time.Now() + key := heldRunApprovalKey(repo, number) + l.mu.Lock() + defer l.mu.Unlock() + if _, ok := l.lookupLocked(key, head, now); ok { + return false + } + l.entries[key] = heldRunApprovalEntry{head: head, seen: now} + return true +} + +// RecordRefusal notes that GitHub refused the approvals on this head and +// what the App's `actions` permission read at the time (grantKnown false +// when it could not be read). +func (l *HeldRunApprovals) RecordRefusal(repo string, number int, head string, runIDs []int64, grant string, grantKnown bool) { + if l == nil { + return + } + key := heldRunApprovalKey(repo, number) + l.mu.Lock() + defer l.mu.Unlock() + entry, _ := l.lookupLocked(key, head, time.Now()) + entry.head, entry.seen = head, time.Now() + entry.refused = true + entry.refusedRuns = append([]int64(nil), runIDs...) + entry.grant, entry.grantKnown = grant, grantKnown + l.entries[key] = entry +} + +// Refused reports whether GitHub refused the approvals on this head, and +// which runs it refused. +func (l *HeldRunApprovals) Refused(repo string, number int, head string) ([]int64, bool) { + if l == nil { + return nil, false + } + l.mu.Lock() + defer l.mu.Unlock() + entry, ok := l.lookupLocked(heldRunApprovalKey(repo, number), head, time.Now()) + if !ok || !entry.refused { + return nil, false + } + return append([]int64(nil), entry.refusedRuns...), true +} + +// ReleaseOnGrant gives a refused head its pass back when the installation +// now grants `actions: write` and did not (or could not be read) when +// GitHub refused. It reports whether it released; the caller then makes +// one more pass, and a second refusal is recorded with the new grant. +func (l *HeldRunApprovals) ReleaseOnGrant(repo string, number int, head, grant string, grantKnown bool) bool { + if l == nil || !grantKnown || !permissionAllowsWrite(grant) { + return false + } + key := heldRunApprovalKey(repo, number) + l.mu.Lock() + defer l.mu.Unlock() + entry, ok := l.lookupLocked(key, head, time.Now()) + if !ok || !entry.refused || (entry.grantKnown && permissionAllowsWrite(entry.grant)) { + return false + } + delete(l.entries, key) + return true +} + +func permissionAllowsWrite(level string) bool { + level = strings.ToLower(strings.TrimSpace(level)) + return level == "write" || level == "admin" +} + +// HeldRunApprovals returns the Client's process-wide held-run ledger. +func (c *Client) HeldRunApprovals() *HeldRunApprovals { + if c == nil { + return nil + } + return &c.heldRunApprovals +} + +// installationPermissionCache holds the installation's granted permission +// map for workflowsGrantTTL. +type installationPermissionCache struct { + mu sync.Mutex + at time.Time + perms map[string]string +} + +// InstallationPermission returns the level ("read", "write", "admin" or +// "" for none) the App installation grants for permission name, read at +// most once per workflowsGrantTTL. known is false for a token-authenticated +// client or a failed read. +func (c *Client) InstallationPermission(ctx context.Context, name string) (level string, known bool) { + if c == nil || c.appAuth == nil { + return "", false + } + name = strings.ToLower(strings.TrimSpace(name)) + cache := &c.installationPerms + cache.mu.Lock() + defer cache.mu.Unlock() + if !cache.at.IsZero() && time.Since(cache.at) < workflowsGrantTTL { + return cache.perms[name], true + } + if ctx == nil { + ctx = context.Background() + } + info, err := installationProbe(ctx, c.appAuth) + if err != nil || info == nil { + return "", false + } + cache.at, cache.perms = time.Now(), info.Permissions + return cache.perms[name], true +} diff --git a/src/pkg/github/held_run_approvals_test.go b/src/pkg/github/held_run_approvals_test.go new file mode 100644 index 0000000000..e06a0e3153 --- /dev/null +++ b/src/pkg/github/held_run_approvals_test.go @@ -0,0 +1,118 @@ +package github + +import ( + "context" + "errors" + "slices" + "testing" + "time" +) + +// The contributor lane's held-run ledger: one pass per PR head, a refusal +// stands until the head changes or the App gains `actions: write`. +func TestHeldRunApprovalsOncePerHeadAndRefusal(t *testing.T) { + var l HeldRunApprovals + if l.Attempted("acme/widget", 7, "sha7") { + t.Fatal("Attempted on an empty ledger = true") + } + if !l.Claim("acme/widget", 7, "sha7") { + t.Fatal("first Claim = false, want true") + } + if l.Claim("ACME/Widget", 7, "SHA7") { + t.Fatal("second Claim on the same head = true, want false") + } + if _, refused := l.Refused("acme/widget", 7, "sha7"); refused { + t.Fatal("Refused before any refusal = true") + } + l.RecordRefusal("acme/widget", 7, "sha7", []int64{12, 11}, "read", true) + runs, refused := l.Refused("acme/widget", 7, "sha7") + if !refused || !slices.Equal(runs, []int64{12, 11}) { + t.Fatalf("Refused = %v %v, want [12 11] true", runs, refused) + } + + // Same grant, a lower one, an unreadable one: the refusal stands. + for _, g := range []struct { + level string + known bool + }{{"read", true}, {"", true}, {"write", false}} { + if l.ReleaseOnGrant("acme/widget", 7, "sha7", g.level, g.known) { + t.Fatalf("ReleaseOnGrant(%q, %v) released, want the refusal to stand", g.level, g.known) + } + } + // The App gained actions: write: one more pass. + if !l.ReleaseOnGrant("acme/widget", 7, "sha7", "write", true) { + t.Fatal("ReleaseOnGrant(write) = false, want a release") + } + if l.Attempted("acme/widget", 7, "sha7") || !l.Claim("acme/widget", 7, "sha7") { + t.Fatal("released head is not claimable again") + } + // Refused again while holding write: no further release. + l.RecordRefusal("acme/widget", 7, "sha7", []int64{11}, "write", true) + if l.ReleaseOnGrant("acme/widget", 7, "sha7", "admin", true) { + t.Fatal("ReleaseOnGrant after a refusal recorded at write = true, want false") + } + + // A new head re-arms the pass and forgets the old refusal. + if _, refused := l.Refused("acme/widget", 7, "sha8"); refused { + t.Fatal("Refused for a new head = true") + } + if !l.Claim("acme/widget", 7, "sha8") { + t.Fatal("Claim on a new head = false, want true") + } + if _, refused := l.Refused("acme/widget", 7, "sha7"); refused { + t.Fatal("old head's refusal survived the new head") + } + // A refusal recorded with an unknown grant releases once write shows. + l.RecordRefusal("acme/widget", 7, "sha8", []int64{11}, "", false) + if !l.ReleaseOnGrant("acme/widget", 7, "sha8", "write", true) { + t.Fatal("ReleaseOnGrant after an unknown-grant refusal = false, want true") + } + // Other PRs are independent; a nil ledger is inert. + if !l.Claim("acme/widget", 8, "sha7") { + t.Fatal("Claim on another PR = false") + } + var nilLedger *HeldRunApprovals + if !nilLedger.Claim("acme/widget", 7, "sha7") || nilLedger.Attempted("acme/widget", 7, "sha7") { + t.Fatal("nil ledger is not inert") + } +} + +func TestHeldRunApprovalsEvictsStaleEntries(t *testing.T) { + var l HeldRunApprovals + l.Claim("acme/widget", 7, "sha7") + l.mu.Lock() + e := l.entries[heldRunApprovalKey("acme/widget", 7)] + e.seen = time.Now().Add(-heldRunApprovalTTL - time.Minute) + l.entries[heldRunApprovalKey("acme/widget", 7)] = e + l.mu.Unlock() + if !l.Claim("acme/widget", 9, "sha9") { + t.Fatal("Claim on another PR = false") + } + if l.Attempted("acme/widget", 7, "sha7") { + t.Fatal("stale entry survived the TTL") + } +} + +func TestInstallationPermissionCachesTheGrant(t *testing.T) { + c := NewClient("token", "acme", []string{"widget"}, nil, "http://127.0.0.1:1") + if level, known := c.InstallationPermission(context.Background(), "actions"); known || level != "" { + t.Fatalf("token client = %q %v, want unknown", level, known) + } + c.appAuth = &AppAuth{} + calls := stubInstallation(t, map[string]string{"actions": "write", "issues": "write"}, nil) + for i := 0; i < 3; i++ { + if level, known := c.InstallationPermission(context.Background(), "Actions"); !known || level != "write" { + t.Fatalf("read %d = %q %v, want write true", i, level, known) + } + } + if *calls != 1 { + t.Fatalf("installation reads = %d, want 1 within the TTL", *calls) + } + + failing := NewClient("token", "acme", []string{"widget"}, nil, "http://127.0.0.1:1") + failing.appAuth = &AppAuth{} + stubInstallation(t, nil, errors.New("boom")) + if _, known := failing.InstallationPermission(context.Background(), "actions"); known { + t.Fatal("failed read reported known") + } +} From 3d6cccb4bbf081fbec41ce8db22de80b5cb2e7d4 Mon Sep 17 00:00:00 2001 From: Danathar Date: Sat, 7 Nov 2026 21:17:34 -0500 Subject: [PATCH 2/4] fix(automerge): drop an unused constant; docs name the contributor lane's grant retry golangci-lint flagged contributorHeldRunsApprovalKeyPrefix as unused after the ledger moved to the long-lived client. The hive reviewer pointed out that github-app-setup.md still said a refused head needs Approve and run after the grant. The contributor lane now retries a refused head once the installation reads actions: write, so the doc says so. hive-merge.md also notes that a ledger entry untouched for 24 hours is dropped. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar --- src/docs/github-app-setup.md | 2 +- src/docs/hive-merge.md | 2 +- src/pkg/github/automerge/automerge_contributor_held_runs.go | 3 --- 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/src/docs/github-app-setup.md b/src/docs/github-app-setup.md index 09c45cff24..e020b3db41 100644 --- a/src/docs/github-app-setup.md +++ b/src/docs/github-app-setup.md @@ -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:` / `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:` / `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 [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. diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index 2cd683aab0..169d28f998 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -894,7 +894,7 @@ nor one touching `.github/workflows/**`. The App needs **Actions: Read and 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), so a refused head is not POSTed again until it changes or the App +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. diff --git a/src/pkg/github/automerge/automerge_contributor_held_runs.go b/src/pkg/github/automerge/automerge_contributor_held_runs.go index 05d81ab8b9..152e970af1 100644 --- a/src/pkg/github/automerge/automerge_contributor_held_runs.go +++ b/src/pkg/github/automerge/automerge_contributor_held_runs.go @@ -34,9 +34,6 @@ const ( // contributorHeldRunsApprovedMarkerPrefix tags the one audit comment the // lane posts after approving a head's held runs. contributorHeldRunsApprovedMarkerPrefix = "