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-fork-guard-across-heads.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A fork PR waiting on a check only a maintainer can run (a fork-guarded check such as a fork Canary) stays with the maintainer across new heads. On projectbluefin/utah-packages#869 and #862 each new head (a merge of the base, or the author's push) read as an ordinary red check until the next enumeration read its annotation, so the PR dropped to 072 and the author was nudged to fix a check they cannot fix. #862 got 13 hive merge-of-main commits, each discarding the exact-head run it waited for. The recorded `fork-guard:` reason now carries onto a new head while the same check is red, the hive no longer updates the branch of a fork head waiting on a fork-guarded check, and the 085 ask names the head the maintainer must run the check for.
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ used to admit the PR:
| `head-changed-since-eval`, `merge-failed`, `merge-queue-required` (the base branch's ruleset only accepts merges through GitHub's merge queue and the transport is a static token that cannot enqueue, so the direct REST merge is refused; with App auth on a repo opted in through `auto_merge.native_merge_queue` these bases are enqueued instead, see [native-merge-queue.md](../native-merge-queue.md); logged as a skip rather than a merge error, [#14018](https://github.com/hivecommons/hive/issues/14018); the self-authored sweep then skips the direct merge on that base for 30 minutes and logs the skip once per PR head, [#14068](https://github.com/hivecommons/hive/issues/14068); the trusted-author, queued and contributor-lane sweeps skip it the same way, sharing one memory of such bases; while a base is remembered the dashboard shows its otherwise-green PRs as a person's to merge, not Merge-eligible; with `auto_merge.require_current_base` on, a head behind such a base is not updated for 24 hours after the last refusal and holds here instead, so the base moving does not reset its review), `required-checks-expected`, `behind`, `updated-branch`, `behind-update-budget-exhausted` (a behind self-authored PR the sweep did not update only because this tick's branch-update budget was spent; retried next tick, waits on the hive, [#12607](https://github.com/hivecommons/hive/issues/12607)), `release-hold*`, `native-merge-queued: queued (position N, STATE)` (the PR was enqueued into GitHub's native merge queue) and the failures `native-merge-queue-read`, `native-merge-queue-enqueue`, `native-merge-queue-method` β€” and no red check on the head | `100-merge-queue` |
| CI red (required or optional check) while the PR is deferred to an open `[shared-ci]` incident (`<!-- hive-shared-ci-<n> -->`, the governor's `deferred_incident`) for the same head | `050-review-pending` / `060-reviewed`, reason `shared-ci-incident:<n>`: the base or a shared check is what is red, so the PR is never sent to 070/071/072, never nudged and never stalled; once the incident closes a still-red head is handed back as usual. Conflicts and requested changes stay author-facing ([#12606](https://github.com/hivecommons/hive/issues/12606)) |
| CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip β€” the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:<check>,<check>` ("waiting for the base branch's CI to recover (…) β€” not this PR's fault"): never 070/071/072, never nudged, never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `<!-- hive-base-branch-red -->` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) |
| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` β€” a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:<check>,<check>`: never 070/071/072, never nudged, never adopted (074) β€” neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or approve the run as the repository requires). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273)) |
| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` β€” a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:<check>,<check>`: never 070/071/072, never nudged, never adopted (074) β€” neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or run or approve it for head `<sha>` as the repository requires). A new head on the same fork PR (a merge of the base, or the author's push) keeps the guard while the lane's red check is one of the recorded `fork-guard:` checks, so the PR does not drop to 072 and nobody is nudged before the annotation for that head is read. The hive also does not update the branch of a fork head that waits on a fork-guarded check: the run a maintainer dispatches proves one exact head, and a merge of the base would discard it. Once the check is green the guard drops and updates resume before merge. A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273), projectbluefin/utah-packages#862 and #869) |
| any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees βœ—). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:<check>` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` β†’ 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) |
| `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `reporter-trust-hold`, `workflow-permission` (GitHub refused update-branch or the merge-forward with a 403 because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission; no token the hive holds can push that update, so it is not sent to 070), `fork-workflow-update` (the same update-branch refusal on a fork head: the App is not installed on the fork, so no grant lets it push there), `linked-issue:hold:#N:<label>` / `linked-issue:needs-decision:#N:<label>` (an open issue the PR closes is held or parked β€” see [Holding an issue](glossary-and-operations.md#holding-an-issue)) | human hand-off, **decision** cause β†’ routed by the head's evidence (below); lands at `085-needs-decision` when the head is otherwise clean. `contributor-lane:workflow-path` reads "awaiting owner approval": a trusted merger's `APPROVED` review on the current head (or a `/hive decision approve`, typed or from the dashboard, which also answers a `requires_human` verdict on that head) releases the fence and the lane merges the PR itself (`owner_approval_releases_workflow_fence`, [#14664](https://github.com/hivecommons/hive/issues/14664)); only with the toggle off, or when the App lacks `workflows: write` for the merge (`hive:unauthorized`, `merge-workflow-path`), does an approved head park at `090-ready-for-human-merge` for a person's click |
| `merge-refused:review-required` (GitHub answered the merge with 405 "At least N approving review(s) is/are required by reviewers with write access"), `merge-refused:method-not-allowed` (405 "Merge commits / Squash merges / Rebase merges are not allowed on this repository") | human hand-off, **decision** cause, as above: lands at `085-needs-decision` when the head is otherwise clean, and the entry comment names the rule GitHub refused the merge on. Every sweep (self-authored, trusted-author, queued, contributor lane) logs these as skips, not `merge-failed` errors, and stops calling merge: a review refusal is remembered per PR head and re-armed when the head moves, when GitHub's `mergeable_state` for the PR changes (an approving review turns `blocked` into `clean`), or after 30 minutes; a method refusal is remembered per repository and method for 30 minutes. The hive never switches the merge method on its own (a forward merge or a `merge-method/merge` PR must not be squashed), so `method-not-allowed` is a manual-merge park. When a person's change request still stands on the PR (their latest review is `CHANGES_REQUESTED`, on any head, and it was neither dismissed nor followed by their approval), the `review-required` comment does not ask for an approval over it. It names each reviewer, the commit they reviewed and a compare link to what the hive pushed since, and asks them to re-review, or a maintainer to dismiss the review. GitHub keeps such a review standing across pushes ([projectbluefin/utah-packages#633](https://github.com/projectbluefin/utah-packages/pull/633)). A 405 "Pull Request has merge conflicts" is reported as `conflicting` (070), not `merge-failed`, and the self-authored sweep re-reads `mergeable_state` right before the merge call and skips a head GitHub now calls `dirty`, so it does not call merge on a conflicting PR. Any other 405, 409 or 422 is still `merge-failed` |
Expand Down
82 changes: 82 additions & 0 deletions src/pkg/github/automerge/automerge_fork_guard_carry.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
package automerge

import (
"strings"

"github.com/hivecommons/hive/pkg/stagelabels"
)

// Fork guard across heads (projectbluefin/utah-packages#869, #862).
//
// The fork guard (hgithub.PullRequest.ForkGuardChecks) is read from the
// failing check's annotation, which the shared-CI index holds per head and
// only after the next enumeration reads it. A new head on a fork PR parked on
// the guard (a merge of the base, or the author's own push) therefore read as
// an ordinary red check for a few minutes: the PR dropped to 072, the author
// was nudged to fix a check only a maintainer can run, and minutes later it
// went back to 085. #862 did that on each of 13 merge-of-main heads.
//
// A fork stays a fork, so the record's `fork-guard:<checks>` reason is carried
// onto the new head while the lane's red check is one of those checks.
// ForkGuardStage still requires a red CI reason and every red optional check
// in the list, so any other failure sends the PR to its author as before.

// laneRedCheck is the check a lane reason names as red, or "".
func laneRedCheck(reason string) string {
r := strings.TrimSpace(reason)
for _, prefix := range []string{"required-check-failing:", "check-failing:", stageReasonOptionalCheckFailing} {
if name, ok := strings.CutPrefix(r, prefix); ok {
return strings.TrimSpace(name)
}
}
return ""
}

// recordedForkGuard is the checks a stage record parked the PR on, or nil.
func recordedForkGuard(rec stagelabels.Record, ok bool) []string {
if !ok {
return nil
}
list, found := strings.CutPrefix(strings.TrimSpace(rec.Reason), stageReasonForkGuard)
if !found {
return nil
}
var out []string
for _, name := range strings.Split(list, ",") {
if name = strings.TrimSpace(name); name != "" {
out = append(out, name)
}
}
return out
}

func obsFromFork(obs stageObservation) bool {
return obs.HeadRepo != "" && obs.Owner != "" && !strings.EqualFold(obs.HeadRepo, obs.Owner+"/"+obs.Repo)
}

// carriedForkGuard offers the record's fork guard for a fork PR head the
// index has not read yet, when the lane's red check is one of its checks.
func carriedForkGuard(rec stagelabels.Record, ok bool, obs stageObservation) []string {
if !obsFromFork(obs) {
return nil
}
checks := recordedForkGuard(rec, ok)
name := laneRedCheck(obs.Reason)
for _, c := range checks {
if c == name {
return checks
}
}
return nil
}

// waitingForkGuard is the fork guard a fork PR head waits on, from the index
// for this exact head: the check is red on it and only a maintainer's
// exact-head run turns it green. A branch update would discard that run, so
// the caller leaves the branch alone while this is non-empty; once the check
// is green the index drops it and updates resume before merge. The stage
// record is not consulted here: a guard it remembers may already be green,
// and skipping on it would keep the PR parked on a check that passed.
func (c *Engine) waitingForkGuard(owner, repo string, number int, head string) []string {
return stageForkGuard(c.stagePolicy(), owner, repo, number, head)
}
Loading
Loading