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/added-native-merge-queue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Automerge sweeps can enqueue eligible PRs into GitHub's native merge queue with the validated head pinned, report queue position and state, and withdraw Hive-enqueued entries only when the PR loses merge eligibility (a hold, a withdrawn or stale approval, changes requested, a paused or disabled repo, or a draft or closed PR) while preserving entries queued by people. The hand-off is opt-in per repo through `auto_merge.native_merge_queue.enabled` and `.repos` (default off; hives without queues see no change). On a queue-enabled base a `blocked` or `behind` PR is enqueued rather than reported `not-mergeable`; the `require_current_base` gate and the `behind` update-branch stay in force unless `auto_merge.native_merge_queue.skip_current_base_gate` is set. The `isMergeQueueEnabled` probe is cached per base branch for `auto_merge.native_merge_queue.probe_ttl` (default 30m) and the entry reconciliation runs only on opted-in repos. A mixed-authorship PR whose queue uses `SQUASH` parks at `stage/085-needs-decision` with the `merge-method` explanation, and the refusal is remembered per head for 30 minutes.
4 changes: 4 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -850,6 +850,10 @@ func runAutoMergeSweepIfDue(ctx context.Context, ghClient *github.Client, cfg *c
return automerge.MergeTrainPolicy{Enabled: cfg.AutoMerge.MergeTrain.IsEnabled(), MaxRebaseAttempts: cfg.AutoMerge.MergeTrain.EffectiveMaxRebaseAttempts()}
}
opts.TrustedBotAuthors = func() map[string]bool { return cfg.AutoMerge.TrustedBotAuthorSet() }
opts.NativeMergeQueue = func() automerge.NativeMergeQueuePolicy {
q := cfg.AutoMerge.NativeMergeQueue
return automerge.NativeMergeQueuePolicy{Enabled: q.Enabled, Repos: q.RepoSet(), SkipCurrentBaseGate: q.SkipCurrentBaseGate, ProbeTTL: q.EffectiveProbeTTL()}
}
}
audit := func(event automerge.AutoMergeSweepEvent) {
if dashSrv == nil {
Expand Down
1 change: 1 addition & 0 deletions src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
### Agent writes and network reference
- [`hive-open-pr`](hive-open-pr.md) — how agents open pull requests as the App bot instead of via `gh pr create`: the flags, the UID-ownership anchor that makes the request forge-resistant, and the asynchronous contract (exit `0` means requested, not opened).
- [`hive-merge`](hive-merge.md) — how agents merge pull requests as the App bot instead of the GitHub MCP `merge_pull_request` tool: the flags, the F4 target-binding (pinned head SHA + governor merge-eligible list), and the retry/re-engagement behavior when required checks are still red.
- [Native merge queue](native-merge-queue.md) — how the auto-merge lanes enqueue eligible PRs into GitHub's native merge queue (App auth only), the `native-merge-queued`/`native-merge-queue-*` stage reasons, and how Hive withdraws only its own entries when a gate breaks.
- [`hive-open-issue`](hive-open-issue.md) — **Agent/developer reference:** request issue creation, comments, or claims through the App bot, with deduplication and retries.
- [Review-bot threads on hive-mediated PRs](review-bot-threads.md) — route bot feedback back to the authoring agent while protecting human review threads.
- [Network and port requirements](network-requirements.md) — inbound ports, proxy paths, egress, and firewall guidance.
Expand Down
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 @@ -365,7 +365,7 @@ used to admit the PR:
| a trusted maintainer answered that question on the same head — `/hive decision <instruction>` or a CHANGES_REQUESTED review (recorded in `review-human-change-requests.json`, head-scoped) | `070-fixing`, reason `contributor-lane:decision-answered`: the answer is folded into the reviewer verdict for that head on every tick and after a restart, so the stage never re-derives 085 from the stale `requires_human` verdict. A bare `/hive decision approve` instead answers that `requires_human` question; it does not remove a `hold` label or provide the broad GitHub-review override for `changes_requested`/`reject`. A new head draws a new verdict with no answer and asks again ([#14679](https://github.com/hivecommons/hive/issues/14679)) |
| CI red (`check-failing:*`, `required-check-failing:*`, `status-*`), `conflicting`, `not-mergeable`, `changes-requested`, verdict changes_requested/reject, `needs-rebase` present | `070-fixing` (self-authored lane or `author/hive`) / `071-needs-author` (`author/human`) / `072-returned-to-contributor` (`author/clanker`) — see [Stage 07x by author kind](#stage-07x-by-author-kind). A head whose App-linked commits carry a `Signed-off-by` the squash would misattribute to the PR author (`hive-signoff-attribution`) follows the same split: the branch owner is the only one who can rewrite them. |
| `contributor-lane:soaking(...)` — and no red check on the head | `095-pre-merge-soak` |
| `head-changed-since-eval`, `merge-failed`, `merge-queue-required` (the base branch's ruleset only accepts merges through GitHub's merge queue, so the direct REST merge is refused; 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), `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*` — and no red check on the head | `100-merge-queue` |
| `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), `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)) |
Expand Down
103 changes: 103 additions & 0 deletions src/docs/native-merge-queue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Native GitHub merge queues

## Opting in

The hand-off is **off by default** and opt-in per repository. A hive that
never sets `auto_merge.native_merge_queue` sees no behaviour change: no lane
probes a queue, enqueues, withdraws an entry or lists a paused repo's PRs, and
a queue-required base still parks at `merge-queue-required`.

```yaml
auto_merge:
native_merge_queue:
enabled: true # default false
repos: [hivecommons/hive] # owner/repo allow-list; empty = every watched repo
skip_current_base_gate: false # default false — see "Current-base gate" below
probe_ttl: 30m # default 30m — see "API cost" below
```

| Key | Default | Meaning |
| --- | --- | --- |
| `auto_merge.native_merge_queue.enabled` | `false` | Turns the native-queue hand-off on. |
| `auto_merge.native_merge_queue.repos` | unset (every watched repo once enabled) | `owner/repo` allow-list, matched case-insensitively. Repos outside it keep the pre-queue behaviour. |
| `auto_merge.native_merge_queue.skip_current_base_gate` | `false` | Lets a queue-enabled base bypass the `auto_merge.require_current_base` gate and the `behind` update-branch. Off keeps both gates in force on queue bases. |
| `auto_merge.native_merge_queue.probe_ttl` | `30m` | How long one base branch's `isMergeQueueEnabled` answer is reused before it is re-read. |

## How it works

Automerge sweeps detect a PR's target queue with GraphQL
`PullRequest.isMergeQueueEnabled`. Once the lane's existing approvals, trust,
holds, review, CI and soak gates allow a merge, Hive calls
`enqueuePullRequest` with `expectedHeadOid` set to the validated head. GitHub
runs the merge group's checks and performs the eventual merge. Branches without
a queue keep the direct REST merge path.

Hive uses its GitHub App installation transport. Static tokens (including a
workflow's `GITHUB_TOKEN`) retain the existing direct-merge behavior and
`merge-queue-required` refusal, since workflow-token events cannot reliably
start `merge_group` workflows. The App installation must grant the existing
merge permissions (`contents: write` and `pull_requests: write`). Permission
or GraphQL failures are surfaced as queue failures; Hive never falls back to
bypassing a detected queue. This change does not request wider App permissions.

Already queued PRs are left in place. The sweep reason reports
`native-merge-queued: queued (position N, STATE)` and maps to
`stage/100-merge-queue`; enqueueing does not emit a completed-merge event or
close an issue. The stage observation carries the reason to the dashboard.

When the owning lane rejects a PR because it lost merge eligibility — a hold
or `do-not-merge`/`needs-human` label, a removed merger label, a missing,
untrusted or stale queue approval, changes requested, or a draft or closed
PR — Hive rechecks the entry's enqueuer and withdraws it only if it belongs to
this App (a `Bot` enqueuer whose login matches the App's slug). Every other
reason, including transient refusals such as `behind`, `not-mergeable`, pending
checks, a moved head, API read errors, author-routing skips and Hive's own
native-queue outcomes, leaves the entry for GitHub's queue to settle. Entries
from a person or another App are preserved.
The queued sweep also withdraws this App's entries on opted-in repositories
that are paused or have automerge disabled. Every enqueue and dequeue uses the
existing mutation boundary, including its write denials. Reconciliation is
periodic/event-driven, so a gate change can race GitHub's eventual merge.

A queue-required base reports `mergeable_state: blocked` (or `behind`) until
the PR merges through the queue, so on a queue-enabled base the queued lane
does not treat those states as `not-mergeable`. A failed queue read keeps the
non-queue behavior.

## Current-base gate

The `auto_merge.require_current_base` gate and the `behind` update-branch stay
in force on a queue-enabled base exactly as on any other base: a behind head
is updated (or parked) before it is enqueued. The merge group does test the
merged result itself, and a pushed head drops the PR from the queue, so an
operator who prefers to let the queue own freshness can set
`auto_merge.native_merge_queue.skip_current_base_gate: true`. That bypass is
explicit and hive-wide for opted-in repos; it is never implied by the presence
of a queue.

## API cost

Each `isMergeQueueEnabled` probe is a GraphQL read. The answer is cached per
`owner/repo#base-branch` for `auto_merge.native_merge_queue.probe_ttl`
(default 30 minutes), so a sweep over many PRs on one base costs one probe,
not one per PR; a read failure is not cached. The per-held-PR entry
reconciliation, the extra `GET /pulls/{n}` the queued lane needs to run it
on a prefiltered PR, and the 10-minute paused-repo PR listing all run only on
repos that opted in through `auto_merge.native_merge_queue`.

Queue rules choose the merge method. Where Hive elected a merge commit to
preserve mixed authorship and DCO attribution, the queue must use `MERGE`;
otherwise Hive reports `native-merge-queue-method` rather than enqueueing.
Like a direct merge GitHub refuses because the merge method is disabled, the
PR parks at `stage/085-needs-decision` for a person, with the `merge-method`
explanation: change the queue's merge method to `MERGE`, or merge it by hand.
The refusal is remembered for 30 minutes per head, so the queue's method is
not re-read every sweep; a new head or the recheck window reads it again.
Read and enqueue failures (`native-merge-queue-read`, `-enqueue`) stay at
`stage/100-merge-queue`; a failure to read the queue's merge method is a
read failure too, not a refusal, and is reported as `native-merge-queue-read`.

Required workflows must subscribe to `merge_group` in addition to their PR
triggers. Workflow-trigger diagnosis is not automatic in this implementation.
See GitHub's [merge queue guide](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)
and [GraphQL pull request reference](https://docs.github.com/en/graphql/reference/pulls).
Loading
Loading