# Publishing as GitHub stacked PRs

> How an agent turns a reviewed stack into GitHub native stacked pull requests.

<!-- Generated by website/scripts/sync-agent-guide.mjs from the "Materializing with GitHub native stacked PRs" section of AGENT-GUIDE.md. Do not edit: change AGENT-GUIDE.md and re-run it. -->

When the reviewer says a stack is ready, the agent pushes its branches, opens one PR per commit with the titles and bodies from [the plan](/agents/plan-command/), links them into a GitHub stack and records each PR back in Local Review. Local Review itself never talks to GitHub.

:::note[From the agent guide]
This page is the [agent guide](/agents/agent-guide/#materializing-with-github-native-stacked-prs)'s "Materializing with GitHub native stacked PRs" section, word for word. Agents read the whole guide with `npx local-review guide`.
:::

**Only when the reviewer asks, one stack at a time:**

1. Fix every warning, run the plan for **one** stack, and **show it to the reviewer**. Skip follow-on stacks unless
   the reviewer names one. If it still has draft PRs, say so:
   the reviewer marks them ready (or tells you to go ahead anyway).
2. **Wait for an explicit go-ahead.**
3. Publish that one stack (below), with its comments for the GitHub PR.
4. Record what you created, and **report back** with the PR URLs and how many comments you posted.
5. Stop. The next stack waits for the next go-ahead.

This uses the [`gh stack` extension](https://github.com/github/gh-stack) (`gh extension install github/gh-stack`).
See [About stacked PRs](https://docs.github.com/en/pull-requests/get-started/about-stacked-prs), the
[CLI reference](https://docs.github.com/en/pull-requests/reference/stacked-prs-cli-commands) and the extension's
[docs](https://github.com/github/gh-stack/tree/main/docs/src/content/docs) (FAQ, REST API). `gh stack` has **no
title or body flags**: `submit` opens an interactive editor, and `--auto` uses generated text. So create each PR
with `gh pr create`, which takes the exact title and body, then link the PRs into a stack with `gh stack link`,
which is meant for branches managed by other tools.

Each repo gets **one GitHub stack**, grown one Local Review stack at a time: the first go-ahead creates it, and each
later one appends to its top by stack number. (Stack numbers share the repo's numberspace with PRs and issues,
so they never equal a PR number.)

```sh
cd ~/code/my-service
local-review plan $P --repo $R --stack 1 --format json > /tmp/plan.json

# 0. stacked PRs available? Any 200 (even `[]`) means yes; 404 means not enabled, or no access to the repo
gh api "repos/{owner}/{repo}/stacks?per_page=1" >/dev/null

# 1. push the stack's branches (bottom to top)
git push --force-with-lease origin $(jq -r '.prs[].branch.name' /tmp/plan.json)

# 2. one PR per branch, bottom to top, with the plan's base, title and full body
jq -c '.prs[]' /tmp/plan.json | while read -r pr; do
  jq -r .body <<<"$pr" > /tmp/pr-body.md
  gh pr create --draft --head "$(jq -r .branch.name <<<"$pr")" --base "$(jq -r .base <<<"$pr")" \
    --title "$(jq -r .title <<<"$pr")" --body-file /tmp/pr-body.md
done

# 3a. first stack in this repo: create the GitHub stack, bottom to top. Always pass --base: without it, link
#     retargets the bottom PR to the repo's default branch.
gh stack link --remote origin --base "$(jq -r '.prs[0].base' /tmp/plan.json)" $(jq -r '.prs[].branch.name' /tmp/plan.json)
# 3b. later stack: append only the new PRs to the existing GitHub stack, by its number (--base is ignored here)
N=$(gh api "repos/{owner}/{repo}/stacks?pull_request=<any earlier PR number>" --jq '.[0].number')
gh stack link --remote origin "$N" $(jq -r '.prs[].branch.name' /tmp/plan.json)

# check: the stack, bottom to top (gh stack view can't see it; see below)
gh api "repos/{owner}/{repo}/stacks?pull_request=$(gh pr view "$(jq -r '.prs[0].branch.name' /tmp/plan.json)" --json number --jq .number)" \
  --jq '.[0] | "stack #\(.number) on \(.base.ref): \([.pull_requests[] | "#\(.number) \(.head.ref)"] | join(" <- "))"'

# 4. record each PR in its prs file (this also records the branch)
for b in $(jq -r '.prs[].branch.name' /tmp/plan.json); do
  sha=$(git rev-parse "$b")
  gh pr view "$b" --json number,url,headRefName,baseRefName \
    | jq '{github: {number, url, branch: .headRefName, base: .baseRefName}}' \
    | curl -s -X PUT -H "$J" -d @- http://localhost:5622/api/projects/$P/repos/$R/commits/$sha/pr >/dev/null
done

# 5. the reviewer's comments for the GitHub PR, as one review per PR (see "Comments for the GitHub PR")
```

Checked against the docs and the extension's source (October 2026):

- **No setup:** stacked PRs are GA on all github.com plans (6 Oct 2026), with no repo or org setting. Step 0 is
  the check. `gh stack` exits `9` for "not enabled for this repository" (a 404 from the Stacks API).
- `link` keeps **no local state**, so `gh stack view`, `push`, `rebase` and `sync` don't know about the stack
  (exit `2`, "not part of a stack"). Read it with `gh api` instead, as above.
- `link` pushes branch arguments **without force**, so push rebased branches with `--force-with-lease` first
  (step 1). It reuses open PRs for those branches and retargets any whose base breaks the chain. It **only adds**,
  and only to the top. A PR can be in only one stack, and a stack holds 2–100 PRs, all in the same repo (no forks).
  Don't pass `--open`: it marks every PR in the command ready for review. Removing or reordering means
  `gh stack unstack <n>` and relinking, which is the reviewer's call.
- A **fully merged** stack can't be extended. The next Local Review stack then becomes a new GitHub stack (3a,
  with the plan's base, which is `main` by then).
- Force-pushing rebased branches keeps the stack: membership belongs to the PRs, not the commits. Merging needs a
  linear history, so each branch must contain the one below it, which `--update-refs` keeps true.
- CI and branch protection treat **every** PR as if it targeted the stack's base, so workflows on `pull_request`
  to `main` run for each PR in the stack. To merge a PR, every PR below it must pass its checks and reviews too.

Not verified (needs a live test):

- splitting one repo's chain into several GitHub stacks, each based on the previous one's top branch. GitHub says
  stacks can branch off one another, but we haven't tried `link --base <previous top branch>`. Use one stack per
  repo;
- whether approvals survive a local force-push. GitHub says its own **Rebase stack** button keeps them, but
  after a local force-push the repo's "dismiss stale approvals" rule probably applies.

Check `gh stack link --help` before you run it, and if anything differs from the above, tell the reviewer rather than guess.

## Comments for the GitHub PR

The reviewer can mark threads **for the GitHub PR** (`publish: true`): comments meant for the PR's readers on GitHub,
not for you. The plan lists them per PR (`publish_threads[]`). Post them as part of publishing their stack (step 5),
after the PRs exist, as **one review per PR** with `event: COMMENT` (never `APPROVE` or `REQUEST_CHANGES`, which are
the reviewer's call): each inline thread at its line, and general, file-level and outdated ones in the review's
body. Line numbers are the commit's, and a stacked PR's diff is exactly its commit's, so they match GitHub's. `side`
`left` is GitHub's `LEFT` (the old file). Post only threads whose `published` is null, and only the reviewer's
comments (skip any `author: claude` reply).

```sh
# 5. per PR with comments to post: the review, then record each thread's GitHub comment
jq -c '.prs[] | select(any(.publish_threads[]; .published == null))' /tmp/plan.json | while read -r pr; do
  N=$(gh pr view "$(jq -r .branch.name <<<"$pr")" --json number --jq .number)
  jq '[.publish_threads[] | select(.published == null) | .comments |= map(select(.author != "claude"))] as $t | {
      commit_id: .commit, event: "COMMENT",
      body: ([$t[] | select(.line == null or .outdated)
        | (if .path then "On `\(.path)`\(if .line then " line \(.line)" else "" end):\n\n" else "" end) + ([.comments[].body] | join("\n\n"))]
        | join("\n\n---\n\n")),
      comments: [$t[] | select(.line != null and (.outdated | not))
        | {path, line, side: (.side | ascii_upcase), body: .comments[0].body}
        + (if .start_line then {start_line, start_side: (.start_side | ascii_upcase)} else {} end)]
    }' <<<"$pr" > /tmp/review.json
  gh api "repos/{owner}/{repo}/pulls/$N/reviews" --input /tmp/review.json > /tmp/review-out.json || break
  RID=$(jq .id /tmp/review-out.json)
  gh api "repos/{owner}/{repo}/pulls/$N/reviews/$RID/comments" > /tmp/review-comments.json
  # record where each one went: an inline thread its comment, the others the review
  jq -c --slurpfile out /tmp/review-out.json --slurpfile cs /tmp/review-comments.json '
    def norm: sub("\\s+$"; "");
    .commit as $sha | .publish_threads[] | select(.published == null) | . as $t
    | (if .line != null and (.outdated | not)
       then first($cs[0][] | select(.path == $t.path and .line == $t.line and (.body | norm) == ($t.comments[0].body | norm)) | {url: .html_url, id})
       else {url: $out[0].html_url, id: $out[0].id} end) as $p
    | {sha: $sha, tid: .id, published: $p}' <<<"$pr" | while read -r x; do
    curl -s -X PATCH -H "$J" -d "$(jq -c '{published}' <<<"$x")" \
      "http://localhost:5622/api/projects/$P/repos/$R/commits/$(jq -r .sha <<<"$x")/threads/$(jq -r .tid <<<"$x")" >/dev/null
  done
done
```

- **An inline thread with more than one comment** (the reviewer added to it): the review carries its first comment.
  Post each later one as a reply, `gh api "repos/{owner}/{repo}/pulls/$N/comments/<id>/replies" -f body=…`, with the
  `id` you recorded.
- **GitHub rejects a line** ("pull_request_review_thread.line must be part of the diff"): the review fails as a
  whole, and nothing is posted. Move that thread into the body (as for outdated ones) and post again.
- **Check:** re-run the plan. Every posted thread now has `published`, and there's no "not posted" warning. Without the
  server, write `published:` (`url`, `id`, `at`) into the thread in the review file instead.
- **Threads marked after a stack went up:** the plan warns for each PR that's on GitHub with comments not posted.
  Post them the same way (step 5 alone), with the reviewer's go-ahead, as for a stack.
- The comments go up under the account `gh` is logged in as. Only ever post `publish: true` threads, never read
  GitHub's comments back into Local Review, and don't change `publish` yourself: it's the reviewer's mark.

## Images

GitHub has no API for attaching an image to a PR body: its upload exists only in the web UI. So an `assets/<name>`
reference in a plan body would show as a broken image on GitHub. For each image the plan warns about, either:

- **record a URL the PR's readers can reach**, with `local-review asset url <project> <name> <url>` (for example an
  image committed to a repo they can read, or one already uploaded to an earlier PR or issue), then re-run the plan:
  the body now has that URL; or
- **leave it to the reviewer**: publish as usual, and tell them which PRs have images to drag in by hand (the plan's
  `images[].file` is where each one is). Dragging an image into the PR on GitHub uploads it; they then replace the
  `assets/<name>` reference with the link GitHub inserts.

Don't upload images anywhere public on your own initiative, and ask before committing one to a repo.
