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-required-checks-rulesets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The automerge sweep reads a branch's ruleset required checks when classic branch protection says nothing is required, so rulesets-only repositories no longer read as "no required checks" and stall at `ci-unverified`; the contributor lane also approves a registry-trusted author's held runs at `ci-unverified` when every `pull_request` run on the head is held.
15 changes: 13 additions & 2 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,8 +469,9 @@ lane's held runs (the `hive-ok-to-test` workflow approves same-repo heads
only). hivecommons/docs#481 by a `trusted` registry contributor sat 17 hours
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>`, it now approves the head's held
runs once (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`, fork head
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
comment naming the author and tier, and logs `contributor-lane approved held
runs` with the run ids (`approve_held_runs_for_registry_trusted`, default
Expand All @@ -480,6 +481,16 @@ 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.

The required checks come from classic branch protection first. When classic
protection says nothing is required (the branch is unprotected, or protected
with no required checks), the sweep also reads the branch's rulesets
(`GET /repos/{owner}/{repo}/rules/branches/{branch}`) and uses their
`required_status_checks` if any. On a rulesets-only repository the classic
answer is always empty, so before this the sweep logged `automerge required
checks source … source=branch known=false count=0`, a held head stayed at
`ci-unverified`, and its runs were never approved (projectbluefin/testsuite,
bluefin-bling).

A PR merges through this tier only when all of the following hold:

- The PR author is admitted by one of three paths:
Expand Down
2 changes: 1 addition & 1 deletion src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,7 +500,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>`, 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 (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`, fork heads included), post one `hive:contributor-held-runs-approved` audit comment and log `contributor-lane approved held runs`. Never acts for claim-marker, auto-promoted or association admissions, sentinel/exclude-labelled PRs, or diffs touching `.github/workflows/**`. Needs the App's **Actions: Read and write** permission. See [hive-merge.md](hive-merge.md#contributor-lane-auto-merge). |
| `auto_merge.contributor_lane.owner_approval_releases_workflow_fence` | `true` | A hive owner / trusted merger's explicit approval on the **current** head — a GitHub `APPROVED` review on that commit, or a dashboard `/hive decision approve` bound to it — releases the contributor lane's `contributor-lane:workflow-path` fence (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. Logs `workflow-path fence released by owner approval`, leaves one `hive:workflow-approval` audit comment per head; approval on an older head does not count. 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
47 changes: 41 additions & 6 deletions src/pkg/github/automerge/automerge_contributor_held_runs.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ package automerge
// is pure drag (hivecommons/docs#481 sat 17h). The lane approves those runs
// once per head with the App token when, and only when, the registry path
// admitted the author and the lane's own CI reason is
// `required-check-missing:<ctx>`. Claim-marker, auto-promotion and
// association admissions stay untouched.
// `required-check-missing:<ctx>`, or `ci-unverified` with every
// `pull_request` run on the head held (a branch whose required checks the
// hive cannot read). Claim-marker, auto-promotion and association
// admissions stay untouched.

import (
"context"
Expand All @@ -35,11 +37,18 @@ const (
// contributorHeldRunsApprovalKeyPrefix namespaces the once-per-head
// bookkeeping inside Engine.heldRunApprovals.
contributorHeldRunsApprovalKeyPrefix = "registry-held-approve:"
// contributorHeldRunsCIUnverified is the commit-CI reason for a head with
// no CI evidence while its required checks are unknown or known-empty.
contributorHeldRunsCIUnverified = "ci-unverified"
)

// approveHeldRunsForRegistryTrusted approves the `action_required` workflow
// runs for a contributor-lane head once, when the author was admitted by the
// registry path and the lane stopped at reason (`required-check-missing:<ctx>`).
// registry path and the lane stopped at reason `required-check-missing:<ctx>`,
// or at `ci-unverified` while every `pull_request` run GitHub has for the
// head is held: with the required set unreadable or known-empty, no CI
// evidence ever appears until someone approves, so the lane would wait
// forever on a contributor the operator already trusts.
// It refuses for any other admission path, when the toggle is off, when the
// PR carries the sentinel or an exclude label, or when the diff touches CI
// definitions. It returns the run ids it approved (nil when it did nothing)
Expand All @@ -55,7 +64,7 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR
if !policy.ApproveHeldRunsForRegistryTrusted || !claim.admittedByRegistry() {
return nil, reason
}
if !strings.HasPrefix(reason, requiredCheckMissingPrefix) {
if !contributorHeldRunsReason(reason) {
return nil, reason
}
labels := labelNames(pr.Labels)
Expand All @@ -73,7 +82,10 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR
}
return nil, reason
}
missing := strings.TrimPrefix(reason, requiredCheckMissingPrefix)
missing := ""
if strings.HasPrefix(reason, requiredCheckMissingPrefix) {
missing = strings.TrimPrefix(reason, requiredCheckMissingPrefix)
}
runs, _, err := c.gh.Actions.ListRepositoryWorkflowRuns(hgithub.WithRESTCaller(ctx, "hive:contributor_lane_automerge_sweep"), owner, repo, &gh.ListWorkflowRunsOptions{
HeadSHA: headSHA,
Event: "pull_request",
Expand All @@ -83,10 +95,16 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR
c.warn("contributor-lane could not list workflow runs for held-run approval", "repo", displayRepo, "pr", number, "head", headSHA, "error", err)
return nil, reason
}
held := heldWorkflowRunsForHead(runs.WorkflowRuns, contributorLaneHeadRepo(pr, owner, repo))
headRepo := contributorLaneHeadRepo(pr, owner, repo)
held := heldWorkflowRunsForHead(runs.WorkflowRuns, headRepo)
if len(held) == 0 {
return nil, reason
}
if missing == "" && len(held) != len(workflowRunsForHeadRepo(runs.WorkflowRuns, headRepo)) {
// ci-unverified with some run already started or finished: the
// 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) {
Expand Down Expand Up @@ -120,6 +138,12 @@ func (c *Engine) approveHeldRunsForRegistryTrusted(ctx context.Context, displayR
return approved, reason
}

// contributorHeldRunsReason reports whether a lane CI reason is one the
// held-run approver acts on.
func contributorHeldRunsReason(reason string) bool {
return strings.HasPrefix(reason, requiredCheckMissingPrefix) || reason == contributorHeldRunsCIUnverified
}

// approveWorkflowRun is POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve.
// go-github v72 has no binding for it.
func (c *Engine) approveWorkflowRun(ctx context.Context, owner, repo string, runID int64) error {
Expand All @@ -143,6 +167,17 @@ func contributorLaneHeadRepo(pr *gh.PullRequest, owner, repo string) string {
return owner + "/" + repo
}

// workflowRunsForHeadRepo returns the runs whose head repository is headRepo.
func workflowRunsForHeadRepo(runs []*gh.WorkflowRun, headRepo string) []*gh.WorkflowRun {
var out []*gh.WorkflowRun
for _, run := range runs {
if run != nil && run.GetHeadRepository() != nil && strings.EqualFold(run.GetHeadRepository().GetFullName(), headRepo) {
out = append(out, run)
}
}
return out
}

// heldWorkflowRunsForHead returns the runs waiting on approval whose head
// repository is headRepo. Unlike heldSameRepoWorkflowRuns the expected head
// repository may be a fork: the PR author's registry tier, not the head's
Expand Down
102 changes: 102 additions & 0 deletions src/pkg/github/automerge/automerge_contributor_held_runs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -450,3 +450,105 @@ func TestUnauthorizedCommentAndMarker(t *testing.T) {
t.Fatalf("reason = %q", got)
}
}

// A rulesets-only repository (projectbluefin/testsuite, bluefin-bling): the
// classic protection answer is "Branch not protected", the ruleset lists the
// required checks. The lane must read the ruleset, stop at
// required-check-missing and approve the registry-trusted author's held runs
// rather than sit at ci-unverified forever.
func TestContributorLaneApprovesHeldRunsOnRulesetsOnlyBranch(t *testing.T) {
fx := validContributorFixture()
fx.baseRef = "main"
fx.body = "Part of #42\n\nSome change."
fx.issueComments = nil
fx.headRepo = "thatguywob/widget"
fx.rulesetContexts = []string{"ci/build", contributorHeldRunsTestContext}
fx.workflowRuns = []map[string]any{heldRun(11, "thatguywob/widget"), heldRun(12, "thatguywob/widget")}
api := newContributorLaneAPI(t, &fx)
defer api.Close()
policy := defaultContributorLanePolicy()
policy.RegistryTiersSufficient = true
policy.ApproveHeldRunsForRegistryTrusted = true
clock := &contributorLaneClock{at: time.Date(2026, 10, 29, 9, 0, 0, 0, time.UTC)}
engine := newContributorLaneEngine(api.URL, policy, clock, Options{ContributorRegistryTier: registryTiers(map[string]string{contributorLaneTestAuthor: "trusted"}), ContributorSoak: soakedTracker(clock)})

_, reason, err := engine.trySweepContributorLanePR(context.Background(), "widget", "acme", "widget", 7, policy)
if err != nil {
t.Fatal(err)
}
if want := requiredCheckMissingPrefix + contributorHeldRunsTestContext; reason != want {
t.Fatalf("reason = %q, want %q (ruleset required checks read)", reason, want)
}
if !slices.Equal(fx.approvedRuns, []int64{11, 12}) {
t.Fatalf("approved runs = %v, want [11 12]", fx.approvedRuns)
}
if fx.merges != 0 {
t.Fatalf("merges = %d, want 0", fx.merges)
}
}

// With no readable required checks a held head reports ci-unverified. The
// approver acts only when every pull_request run on the head is held; a head
// where some run already started is an ordinary evidence gap.
func TestContributorLaneApprovesHeldRunsWhenCIUnverifiedAndAllHeld(t *testing.T) {
for _, tc := range []struct {
name string
runs []map[string]any
registry map[string]string
wantApproved []int64
}{
{
name: "every run held approves",
runs: []map[string]any{heldRun(11, "acme/widget"), heldRun(12, "acme/widget"), 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"}},
},
registry: map[string]string{contributorLaneTestAuthor: "trusted"},
},
{
name: "claim marker author is not approved for",
runs: []map[string]any{heldRun(11, "acme/widget")},
registry: nil,
},
} {
t.Run(tc.name, func(t *testing.T) {
fx := validContributorFixture()
fx.baseRef = "main"
if tc.registry != nil {
fx.body = "Part of #42\n\nSome change."
fx.issueComments = nil
}
fx.noCIEvidence = true
fx.workflowRuns = tc.runs
api := newContributorLaneAPI(t, &fx)
defer api.Close()
policy := defaultContributorLanePolicy()
policy.RegistryTiersSufficient = true
policy.ApproveHeldRunsForRegistryTrusted = true
clock := &contributorLaneClock{at: time.Date(2026, 10, 29, 9, 0, 0, 0, time.UTC)}
engine := newContributorLaneEngine(api.URL, policy, clock, Options{ContributorRegistryTier: registryTiers(tc.registry), ContributorSoak: soakedTracker(clock)})

for tick := 1; tick <= 2; tick++ {
_, reason, err := engine.trySweepContributorLanePR(context.Background(), "widget", "acme", "widget", 7, policy)
if err != nil {
t.Fatalf("tick %d: %v", tick, err)
}
if reason != contributorHeldRunsCIUnverified {
t.Fatalf("tick %d reason = %q, want %q", tick, reason, contributorHeldRunsCIUnverified)
}
}
if !slices.Equal(fx.approvedRuns, tc.wantApproved) {
t.Fatalf("approved runs = %v, want %v (once across two ticks)", fx.approvedRuns, tc.wantApproved)
}
if fx.merges != 0 {
t.Fatalf("merges = %d, want 0", fx.merges)
}
})
}
}
2 changes: 1 addition & 1 deletion src/pkg/github/automerge/automerge_contributor_lane.go
Original file line number Diff line number Diff line change
Expand Up @@ -1384,7 +1384,7 @@ func (c *Engine) evaluateContributorLanePR(ctx context.Context, displayRepo, own
return eval, reason, err
}
if !green {
if strings.HasPrefix(reason, requiredCheckMissingPrefix) {
if contributorHeldRunsReason(reason) {
_, reason = c.approveHeldRunsForRegistryTrusted(ctx, displayRepo, owner, repo, pr, number, headSHA, claim, policy, files, reason)
}
if !strings.HasPrefix(reason, unauthorizedReasonPrefix) {
Expand Down
22 changes: 22 additions & 0 deletions src/pkg/github/automerge/automerge_contributor_lane_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,12 @@ type contributorLaneFixture struct {
// unprotected. The status/check-runs routes only ever report ci/build,
// so any other name yields required-check-missing:<name>.
requiredContexts []string
// rulesetContexts, when set with baseRef, is what the branch's rulesets
// (rules/branches) list as required_status_checks; empty serves [].
rulesetContexts []string
// noCIEvidence makes the status and check-runs routes for sha7 report
// nothing, as for a head whose only workflow runs GitHub is holding.
noCIEvidence bool
// workflowRuns is the payload of GET actions/runs?head_sha=sha7; nil
// serves an empty list.
workflowRuns []map[string]any
Expand Down Expand Up @@ -302,13 +308,21 @@ func newContributorLaneAPI(t *testing.T, fx *contributorLaneFixture) *httptest.S
json.NewEncoder(w).Encode(fx.reviews)
case r.Method == http.MethodGet && (r.URL.Path == "/repos/acme/widget/commits/sha7/status" ||
(fx.recheckHeadSHA != "" && r.URL.Path == "/repos/acme/widget/commits/"+fx.recheckHeadSHA+"/status")):
if fx.noCIEvidence {
json.NewEncoder(w).Encode(map[string]any{"state": "pending", "total_count": 0, "statuses": []any{}})
return
}
json.NewEncoder(w).Encode(map[string]any{
"state": headStatus,
"total_count": 1,
"statuses": []map[string]string{{"context": "ci/build", "state": headStatus}},
})
case r.Method == http.MethodGet && (r.URL.Path == "/repos/acme/widget/commits/sha7/check-runs" ||
(fx.recheckHeadSHA != "" && r.URL.Path == "/repos/acme/widget/commits/"+fx.recheckHeadSHA+"/check-runs")):
if fx.noCIEvidence {
json.NewEncoder(w).Encode(map[string]any{"total_count": 0, "check_runs": []any{}})
return
}
run := map[string]string{"name": "build", "status": "completed", "conclusion": headStatus}
if fx.checkCompletedAt != "" {
run["completed_at"] = fx.checkCompletedAt
Expand Down Expand Up @@ -361,6 +375,14 @@ func newContributorLaneAPI(t *testing.T, fx *contributorLaneFixture) *httptest.S
}
w.WriteHeader(http.StatusCreated)
case fx.baseRef != "" && r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/rules/branches/"+fx.baseRef:
if len(fx.rulesetContexts) > 0 {
checks := make([]map[string]string, 0, len(fx.rulesetContexts))
for _, name := range fx.rulesetContexts {
checks = append(checks, map[string]string{"context": name})
}
json.NewEncoder(w).Encode([]any{map[string]any{"type": "required_status_checks", "parameters": map[string]any{"required_status_checks": checks}}})
return
}
json.NewEncoder(w).Encode([]any{})
case fx.baseRef != "" && r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/commits/base1/status":
json.NewEncoder(w).Encode(map[string]any{"state": "success", "total_count": 0, "statuses": []any{}})
Expand Down
2 changes: 2 additions & 0 deletions src/pkg/github/automerge/automerge_sweep_guards_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,8 @@ func newSelfSweepGuardAPI(t *testing.T, fx selfSweepFixture) *httptest.Server {
return
}
json.NewEncoder(w).Encode(map[string]any{"merged": fx.mergeApplied, "sha": "merge7"})
case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/rules/branches/"):
json.NewEncoder(w).Encode([]any{}) // no rulesets
default:
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.String())
}
Expand Down
Loading
Loading