Skip to content

feat(pr-pipeline): merge the bottom layer of a native stack from the merge lane - #17541

Open
kyle-sexton wants to merge 4 commits into
mainfrom
feat/15410-merge-lane-stack-bottom-layer
Open

kyle-sexton wants to merge 4 commits into
mainfrom
feat/15410-merge-lane-stack-bottom-layer

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Refs: #15410
Hold: waits for the sandbox run issue #15410's done-when asks for

Summary

The merge lane can now land the bottom layer of a native GitHub stack whose stack base is main, as the owner decided on #15410 (option B, 2026-11-17). GitHub refuses native auto-merge for every stack member ("Auto-merge is not supported for stacked pull requests", sandbox #327 in #15400), so where enable-auto-merge.mjs would arm such a layer it now sends the asynchronous merge instead. Issue-lane stacking is split out to #17539; nothing under .github/scripts/work-resolve-issue changes.

Fix

.github/scripts/pr-merge/enable-auto-merge.mjs:

  • PULLS_QUERY also reads each pull request's stack { baseRefName entries { position pullRequest { number state } } } (GraphQL PullRequestStack). No extra call.
  • stackPlace(pull): a pull request in no stack is unchanged. A layer is the bottom only when its stack targets main and no entry at a lower position is OPEN. Any other layer (an open layer below it, a stack into another branch, entries not read whole) gets none in decide before any read, so it is never merged and never armed.
  • A bottom layer goes through every rule an arm goes through (hold labels, body holds, member vetoes, hold and cost paths, the verifier verdict, the risk score, the room cap). Where decide would arm it, it also needs ciStatus === "success": the newest CI Status check run at the head, read on the job token (ciStatusAt). Anything else (pending, failure, missing, unread) leaves it with no comment, as a check still running leaves a native arm waiting.
  • After the same pin comment, evidence comment and Merge-Risk record an arm gets, it sends PUT /repos/{owner}/{repo}/pulls/{n}/merge-async with sha = the head read and bypass_rules: false. Into main's merge queue (merge_action: merge_queue) when repository.mergeQueue(branch: "main") names one, else direct_merge with merge_method: squash, as the native arm squashes.
  • Answers: 2xx is requested; 409 (a request already pending) is logged, not refused and not resent; any other 4xx but 401 and 429, 403 included, leaves the layer unmerged and posts the refusal comment through the existing note() path with clears: "person" (comment plus the human-gated label). Anything else fails the run as a failed arm does.
  • A 202 is only accepted, and the background merge can still end failed (Get the result of an asynchronous merge), so the lane reads the result by its uuid up to six times, five seconds apart; failed goes to the same refusal comment, merged or enqueued is requested, and one still pending is left for the next run (whose send answers 409 while it is pending).
  • Before sending, it reads the layer's merge queue entry (QUEUE_ENTRY_QUERY): a layer an earlier run enqueued is still open with no auto-merge, so it is left ("its async merge already put it in main's merge queue"), neither sent again nor counted again toward the room. An unread entry sends nothing that run.

Design choices and their basis:

  • Async merge endpoint and fields: Merge a pull request asynchronously (present under the 2022-11-28 API version this client sends): "This is the required API for merging stacked pull requests. For a stacked pull request, the operation includes all open downstack pull requests"; sha "that pull request head must match"; merge_method "Only supported for direct merges"; merge_action merge_queue / direct_merge; "Contents" write, which the lanes App token already holds for the disarm (enable-auto-merge.mjs Environment, GH_TOKEN). No credential, token permission or workflow permissions: block changes.
  • Bottom = no open layer below, not position === 1: the endpoint takes every open downstack pull request with it, so this is the condition under which the lane lands this one layer alone; it holds whether or not GitHub renumbers positions after a lower layer merges (unverified).
  • CI Status before the call: the endpoint says "Branch protection rules and repository rules are not run at this stage". The job token has checks: read (pr-merge.yml enable-auto-merge job, permissions:); the lanes App token has no checks permission. The read is inline, not an import of pr-unblock/review-dependency.mjs, because ci-status loads this module from a sparse checkout (pr-require-checks.yml, "base-config" checkout) that does not hold that file.
  • Merge queue read: merge_method applies only to a direct merge, and this repository's main has a queue while a repository without one needs the squash method; one GraphQL read per stack merge settles it.
  • Refusal routing, clears: "person": a refused call (403 a token that cannot merge, 400 not mergeable, 422) is not something the next scheduled run fixes, and the owner's criterion is "leaves the layer unmerged with an explanatory comment and adds no credential". The existing refused() treats 403 as run-wide and posts nothing, so the merge path has its own mergeRefused.

Docs: plugins/source-control/reference/stacked-prs.md says the merge lane lands only the bottom layer; changelog fragments for pr-pipeline (minor) and source-control (patch).

Verification

  • node --test --test-concurrency=4 .github/scripts/pr-merge/enable-auto-merge.test.mjs: 243 pass, 0 fail. New tests, one per done-when case plus four:
    • "a green stack bottom layer is merged through the async merge at its head, never armed; a pull request in no stack still arms" (also a layer whose lower layer already merged)
    • "into a merge queue, the async merge enqueues the bottom layer with no merge method"
    • "a held stack bottom layer is not merged: a hold label, a body hold, a member veto, or a CI Status not green at its head"
    • "a layer above the bottom is not merged, nor one of a stack into another branch or a stack not read whole"
    • "a refused async merge leaves the layer unmerged with a person's explanatory comment, and the run goes on"
    • "an async merge already pending is neither a refusal nor sent again"
    • "a bottom layer already in main's merge queue is neither sent again nor counted again toward the room"
    • "an accepted async merge whose result ends failed leaves the layer with a person's explanatory comment; one that merges or enqueues does not"
  • bash scripts/check-affected.sh: 17 passed, 3 skipped over the changed files.

Remaining

  • Sandbox run (done-when item 6), not done. The sandbox's pr-merge.yml runs .base/.github/scripts/pr-merge/enable-auto-merge.mjs from its own main, so this branch's script reaches it only through a sandbox resync after this merges (or a sandbox PR copying it onto the sandbox's main). The run also needs a two-layer stack whose layers the lanes App authored (decide acts only on lanes App pull requests), which a session without the lanes App token cannot open. Once both hold: a scheduled or hand-started sandbox pr-merge.yml run should show the bottom layer merged through merge-async and the upper layer left with "it is a layer above the bottom of its stack". pr-pipeline: merge and issue lanes for native stack layers #15410 stays open until that run is linked.

Related

🤖 Generated with Claude Code

kyle-sexton and others added 3 commits November 19, 2026 16:38
…merge lane

GitHub refuses native auto-merge for every stack member, so the merge
lane could never land a stack layer. enable-auto-merge.mjs now reads
each listed pull request's stack. A layer of a stack into main with no
open layer below it is judged by every rule an arm checks; where it
would arm, the lane sends the async merge instead, pinned to the head
it read, into main's merge queue when there is one, and only once the
newest CI Status run at that head passed. Any other layer is left. A
merge GitHub refuses leaves the layer unmerged with a person's refusal
comment; no credential is added.

Refs: #15410

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…merge lane line

Refs: #15410

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs: #15410

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton

Copy link
Copy Markdown
Member Author

Session hold (GitHub Work): this pull request waits for the sandbox run that issue #15410's done-when asks for; the label comes off when that run is linked in the body.

@kyle-sexton kyle-sexton added do-not-merge Hard merge gate: do not merge while applied. and removed do-not-merge Hard merge gate: do not merge while applied. labels Nov 19, 2026
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 19, 2026 23:05
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T23:08:03.623806Z 92f6046 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 19, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 92f60464cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +2624 to +2627
await github("PUT", `/repos/${repo[0]}/pulls/${pull.number}/merge-async`, mergeAsyncBody(pull.headRefOid, queue.mergeQueue != null));
leave(pull, "merge requested");
console.log(`enable-auto-merge: #${pull.number} stack bottom layer: async merge requested at ${pull.headRefOid}`);
statuses.push({ sha: pull.headRefOid, state: "success", description: "async merge requested for its stack's bottom layer" });

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Read the asynchronous merge result before discarding its UUID

When GitHub accepts the request with HTTP 202 but subsequently rejects the merge during background processing, this path discards the UUID and never observes the failure. The async merge documentation specifies a final failed result containing the failure message; acceptance itself does not establish that the merge can proceed. Consequently, such a layer receives neither the explanatory refusal comment nor the human-gated label implemented below, and later sweeps can keep submitting the same unsuccessful request. Retain and check the asynchronous result, routing a final rejection through the refusal handling.

Useful? React with 👍 / 👎.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 8b474910674ff5f41b879f2204a6aafae533e1d8: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Security review (incremental, blocking only): no security issues found

Scope: the push since 92f60464, which changes .github/scripts/pr-merge/enable-auto-merge.mjs and its test file. I read every hunk of both. enable-auto-merge.mjs is a merge-hold control, so I checked whether the change widens or narrows any hold. Because an earlier head was already reviewed, this review reports only CRITICAL and IMPORTANT findings.

Merge holds: none weakened

  • The new queue-entry check only adds restriction. It runs only when decide already returned arm for a stack bottom layer (L2536). It can only change arm to none:
    • when the entry is unread, it fails closed and nothing is sent that run;
    • when the layer is already enqueued, it is left alone.
      No hold rule is skipped. A layer that gets a hold after it was enqueued never reaches this branch, because decide no longer returns arm for it. The existing dequeue-on-hold path is unchanged.
  • Polling the async merge result only adds a refusal path. A result of failed now goes to the existing note() path with clears: "person": a comment plus the human-gated label, and inFlight is decremented. merged, enqueued, or a result still pending after six reads keeps the earlier "requested" behaviour. So no layer that was held before is now let through.

Tokens and untrusted text: nothing widened

  • No new permissions. No new credential, token scope or permissions: change. The result GET uses the same lanes App token as the existing PUT.
  • The uuid is encoded before it goes into the URL. It comes from GitHub's own 202 response and passes through encodeURIComponent, so it cannot change the request path.
  • The failure comment carries only GitHub's text. details.message comes from the GitHub API, not from the PR author, and passes through escapeCommand before it reaches the log and the comment.

Spend: up to six extra REST reads, five seconds apart, per async merge of a stack bottom layer, plus one GraphQL queue-entry read per bottom layer the lane would arm. These use existing tokens and Actions minutes.

PR context: nothing in the description or linked issue tries to direct the review.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

claude-review: 1 inline finding(s) on 92f60464cc18c3bcaa1da5b03335a73039fb447e; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment on lines +2610 to +2633
if (action === "arm" && stackPlace(pull) === STACK_BOTTOM) {
leave(pull, "refused: its async merge failed");
let queue;
try {
queue = (await github("POST", "/graphql", { query: MERGE_QUEUE_QUERY, variables: { owner: repo[1], name: repo[2] } }))?.data?.repository;
} catch (error) {
console.log(`enable-auto-merge: #${pull.number} main's merge queue did not read: ${describe(error)}`);
}
if (queue == null) {
failed += 1;
console.log(`::error title=enable-auto-merge::#${pull.number} async merge not sent: main's merge queue did not read`);
continue;
}
try {
await github("PUT", `/repos/${repo[0]}/pulls/${pull.number}/merge-async`, mergeAsyncBody(pull.headRefOid, queue.mergeQueue != null));
leave(pull, "merge requested");
console.log(`enable-auto-merge: #${pull.number} stack bottom layer: async merge requested at ${pull.headRefOid}`);
statuses.push({ sha: pull.headRefOid, state: "success", description: "async merge requested for its stack's bottom layer" });
} catch (error) {
if (error instanceof GitHubError && error.status === 409) {
leave(pull, "merge requested");
console.log(`enable-auto-merge: #${pull.number} stack bottom layer: an async merge is already pending`);
} else if (mergeRefused(error, answer?.limited)) {
inFlight -= 1;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The merge is re-sent every run, and a duplicate that comes back as anything but 409 dequeues a healthy queued merge.

After merge-async with merge_action: "merge_queue" succeeds, the layer is still OPEN with autoMergeRequest == null. Nothing in the listing or in decide reads whether it is already queued (DETAIL_QUERY and PULLS_QUERY read no mergeQueueEntry). So on the next scheduled run, while the layer waits in the queue:

  1. decide returns arm again, and line 2535 adds it to inFlight a second time. lane.count likely already counts the queue entry, so the double count can hold back other pull requests at the room cap.
  2. The evidence comment and the Merge-Risk record run again.
  3. PUT .../merge-async is sent again.

The only safeguard is the 409 branch at 2629, which assumes GitHub answers 409 for "already pending". That assumption is unverified: only a mocked 409 tests it, and on GitHub's sync merge endpoint 409 means the head SHA did not match. If the real answer is a 405 or 422, mergeRefused posts a person's refusal and adds the human-gated label, and note's leaveQueue then dequeues the layer. A healthy queued merge gets pulled and parked for a person.

The same applies when withRetry resends the PUT after a lost answer and the first send landed. The arm path reads the state back in sendSettled for exactly this case. This path does not, and the inFlight -= 1 at 2633 also ignores error.attempts, unlike line 2673.

How it fails: a merge-queue repository, a green bottom layer, and two scheduled runs before the queue lands it. With the second PUT answered 422, the test world records a refusal comment, the needs-human label and a dequeue.

Fix: before sending, read the layer's queue entry (QUEUE_ENTRY_QUERY, already imported) and treat a queued layer as in flight: none, already queued, no extra inFlight. On an error after a resend, read the state back before routing it to mergeRefused, as sendSettled does.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 8b474910674ff5f41b879f2204a6aafae533e1d8: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental, blocking only): 92f6046 → 8b47491

I read the whole incremental change in both listed files: .github/scripts/pr-merge/enable-auto-merge.mjs and .github/scripts/pr-merge/enable-auto-merge.test.mjs. I also read the unchanged code the new lines call: QUEUE_ENTRY_QUERY in pr-unblock/address-feedback.mjs, the initial inFlight count, roomHold, note()'s early return when clears is undefined, and withRetry. An earlier head was already reviewed, so this review reports only blocking findings.

Prior finding (discussion_r4636384641): addressed.

  • Duplicate sends. Before sending, a stack-bottom arm now reads the layer's mergeQueueEntry (enable-auto-merge.mjs#L2536-L2548).
    • A layer already queued turns into none before roomHold and inFlight += 1 run, so it is not sent again and not counted again. lane.count already counts it, and the initial inFlight excludes lane.queued from the armed term.
    • An unread entry sends nothing that run.
    • Neither branch posts a comment: the arm's clears is undefined, so note() returns early. The new test asserts no notes, no merge, and the other pull request still arming.
  • Resends after a lost answer. This part does not apply. withRetry resends only GraphQL mutations (#L452-L466), so the REST PUT .../merge-async goes out once. The inFlight -= 1 on a refusal therefore needs no attempts check.

New in this push: after a pending 202, the lane polls the async-merge result: up to 6 reads, 5 s apart, by details.uuid.

  • A failed result goes to the same person-refusal path as a refused send.
  • A failed read stops polling, and the run logs the merge as requested.
  • A result still pending after the reads is left for the next run. That run's queue-entry read or 409 handles it.

The tests cover failed, merged, enqueued, and still pending after six reads. I found no blocking defect.

Closing issue: the PR says Refs: #15410 and closes no issue, so there are no acceptance criteria to check.

Embedded text: neither the PR context nor the prior-findings file tells the lane to approve, skip, or post elsewhere.

Verification: I ran nothing (no shell). The PR body's "243 pass, 0 fail" and check-affected.sh results are the author's claims and unverified.

Plugin manifests: no plugin.json or marketplace.json changed in this push.

Paved paths: I did not resolve a standards index; no paved-path entry was cited.

Loosened-check verdict: fail (default; the prompt carried no loosened_check_verdict: or loosened_check_patterns: line); patterns: 0. No changed line loosens a check: the test edits add tests and extend the mocked world. The prompt had no loosened_check_decision_record: line, so the citation requirement was not checked.

Spend (not a hold, not counted): each stack-bottom merge now adds one GraphQL queue-entry read per run, plus up to six result reads and 30 s of runner wait after a pending 202, on existing tokens and Actions minutes.

No verifier subagent ran this round. Verifier dropped 0 of 0 candidates.

… layer

A 202 from merge-async is only accepted: the merge runs in the background
and can end failed. The lane now reads the result up to six times, five
seconds apart, and routes a failed one to the person's refusal comment.

A bottom layer an earlier run put in main's merge queue is still open with
no auto-merge, so every run re-sent it and counted it again toward the
room. The lane now reads its merge queue entry first and leaves a queued
layer alone.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do-not-merge Hard merge gate: do not merge while applied.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant