docs: record GitHub stacked PR merge surface - #1441
Conversation
- Document the preview REST endpoints and merge semantics. - Record the missing CLI, REST, and GraphQL merge operation. 🤖 Generated with [Codex](https://github.com/openai/codex) Co-authored-by: codex <codex@users.noreply.github.com>
📝 WalkthroughWalkthroughChangesGitHub stacked PR merge documentation
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/investigations/github-stacked-pr-merge.md`:
- Around line 7-15: Update the investigation wording around the Stacks API to
distinguish missing stack-aware merge behavior from the available generic
pull-request merge operation. Preserve the documented stack endpoints, but
explicitly acknowledge GitHub’s generic PUT pull-request merge endpoint and
avoid claiming that REST has no merge operation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: ae384b56-8e20-43db-be61-1c98c4dee79c
📒 Files selected for processing (1)
docs/investigations/github-stacked-pr-merge.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
**/*: Keep implementation patches minimal; do not refactor, rename, or generalize unless required by correctness, architecture, or task scope.
Before asking factual questions, search the repository and document the paths, patterns, and docs searched.
Before claiming a UI or feature is absent, search the relevant frontend component, page, feature, store, and library directories using contains-match patterns.
When introducing a new invariant, document it with the next available ID, add enforcing tests, and reference it near code when the constraint is non-obvious.
Files:
docs/investigations/github-stacked-pr-merge.md
**
⚙️ CodeRabbit configuration file
**: Architecture, invariants, and the full app inventory live in CLAUDE.md and
docs/system-overview.md. Treat those as the source of truth.What NOT to flag:
- Pre-existing issues not introduced by this PR
- Issues that TypeScript compilation or ESLint would catch (types, imports, lint)
- Stylistic preferences without a concrete rule violation in CLAUDE.md
- Theoretical risks or hypothetical edge cases without evidence of exploitability
- General best-practice suggestions that don't map to a specific project rule
Security calibration:
- React JSX is safe from XSS unless dangerouslySetInnerHTML is used
- ULIDs/UUIDs are cryptographically unguessable — do not flag as enumeration risks
- Environment variables are trusted — do not flag as hardcoded secrets
- DoS, rate limiting, log spoofing, regex complexity, missing audit logs, and
outdated dependency warnings are out of scopePlan adherence:
The implementation plan is in the PR description, inside the collapsible
"📋 Full implementation plan" details block (plans are not committed to the repo).
If that block exists, check that PR changes align with the plan.
Flag missing corresponding changes: API change without frontend/backoffice update,
type change without usage update, schema change without migration.
Files:
docs/investigations/github-stacked-pr-merge.md
🧠 Learnings (1)
📚 Learning: 2026-05-30T19:08:44.359Z
Learnt from: kristofferremback
Repo: threahq/threa PR: 706
File: docs/features/README.md:29-33
Timestamp: 2026-05-30T19:08:44.359Z
Learning: In threahq/threa Markdown documentation, allow bare fenced code blocks (no language/info tag) when they’re intentionally used to display file/directory tree listings. Do not flag these blocks with markdownlint rule MD040 and do not recommend adding a `text` (or any other) language identifier as an info tag.
Applied to files:
docs/investigations/github-stacked-pr-merge.md
🔇 Additional comments (1)
docs/investigations/github-stacked-pr-merge.md (1)
1-3: LGTM!Also applies to: 17-20
| `gh stack` v0.0.8 creates, updates, rebases, syncs, and dissolves stacks, but has no merge command. GitHub's preview [REST reference](https://github.github.com/gh-stack/reference/rest-api/) documents these endpoints: | ||
|
|
||
| - `GET /repos/{owner}/{repo}/stacks` | ||
| - `GET /repos/{owner}/{repo}/stacks/{stack_number}` | ||
| - `POST /repos/{owner}/{repo}/stacks` | ||
| - `POST /repos/{owner}/{repo}/stacks/{stack_number}/add` | ||
| - `POST /repos/{owner}/{repo}/stacks/{stack_number}/unstack` | ||
|
|
||
| The stack resource includes its base and ordered pull requests. Pull request resources also expose stack number, size, position, and base. Public GraphQL introspection exposes no stack type or mutation. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== docs/investigations/github-stacked-pr-merge.md ==="
nl -ba docs/investigations/github-stacked-pr-merge.md | sed -n '1,80p'
echo
echo "=== Search for stack metadata / merge wording ==="
rg -n "stack|merge operation|pulls/\\{pull_number\\}|pulls\\}|stacks" docs/investigations/github-stacked-pr-merge.md
echo
echo "=== Repo docs mentioning GitHub stacked PR merge ==="
rg -n "github-stacked-pr-merge|gh stack|stack-aware|atomic merge|pull-request merge" docs CLAUDE.md docs/system-overview.mdRepository: threahq/threa
Length of output: 246
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== docs/investigations/github-stacked-pr-merge.md (lines 1-120) ==="
cat -n docs/investigations/github-stacked-pr-merge.md | sed -n '1,120p'
echo
echo "=== related references in repo ==="
rg -n "pulls/\\{pull_number\\}|stack-aware|atomic merge|merge operation|gh stack|stacks API|stack metadata" docs CLAUDE.md .Repository: threahq/threa
Length of output: 7184
🌐 Web query:
GitHub gh-stack reference REST API pull requests stack number size position base merge endpoint
💡 Result:
In the context of GitHub Stacked PRs, the stack object provides metadata about a pull request's membership and position within a stack [1]. While this data is fully available in webhook event payloads, its exposure via the official REST API is currently limited [1][2]. The stack object, when present (e.g., in webhooks), contains the following primary fields [1]: - stack.id: A global, unique identifier for the stack [1]. - stack.number: A repository-scoped identifier for the stack, which now serves as the primary way to reference a stack in the GitHub CLI (gh stack) [1][3]. - stack.size: The total number of pull requests currently in the stack [1]. - stack.position: The 1-based position of the specific pull request within the stack, where 1 is the bottom-most PR (closest to the stack's base) [1]. - stack.base.ref: The branch the entire stack ultimately targets (e.g., main) [1]. - stack.base.sha: The HEAD SHA of the stack's base branch [1]. Regarding API access, while an internal endpoint (repos/{owner}/{repo}/cli_internal/pulls/stacks) exists for CLI operations, it generally provides membership info but lacks the full metadata (such as the base branch) found in webhook payloads [2]. Users and developers are encouraged to rely on webhook events for programmatic access to full stack state, as read-only REST and GraphQL APIs for stack metadata have historically been constrained or unavailable [2]. The GitHub CLI (gh stack) manages these operations locally, allowing users to reference stacks via the stack number for commands like checkout, unstack, and view [4][3].
Citations:
- 1: https://github.github.com/gh-stack/reference/webhooks/
- 2: `stack` object is webhook-only — expose pull request stack membership on REST & GraphQL github/gh-stack#139
- 3: Stack number as primary identifier github/gh-stack#178
- 4: https://github.github.com/gh-stack/reference/cli/
🌐 Web query:
site:github.github.com/gh-stack/reference/rest-api/ pull requests stack metadata GET /repos/{owner}/{repo}/pulls GET /repos/{owner}/{repo}/pulls/{pull_number} merge endpoint
💡 Result:
GitHub exposes stacked pull request metadata through its REST API [1]. A stack object is included in pull request resources, meaning that pull requests returned by the REST API may contain specific information regarding their inclusion in a stack [1]. To retrieve pull request information, the following GitHub REST API endpoints are generally used: 1. List pull requests: GET /repos/{owner}/{repo}/pulls 2. Get a single pull request: GET /repos/{owner}/{repo}/pulls/{pull_number} When interacting with these endpoints, the pull request response object includes various fields related to the state and details of the pull request [2]. To merge a pull request via the GitHub REST API, use the following endpoint: PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge This endpoint allows you to merge a pull request if it meets the necessary conditions, such as passing required status checks. Ensure your request includes the appropriate authentication headers and any required body parameters, such as the commit message or merge method (e.g., merge, squash, or rebase), depending on the repository settings and your requirements.
Citations:
- 1: https://github.github.com/gh-stack/reference/rest-api/
- 2: https://docs.github.com/en/enterprise-server@3.17/rest/activity/events
🌐 Web query:
site:github.github.com/gh-stack/reference/rest-api/ "GET /repos/{owner}/{repo}/pulls" "GET /repos/{owner}/{repo}/pulls/{pull_number}" "stack" "merge"
💡 Result:
The GitHub REST API provides endpoints to interact with pull requests and stacks, though stack merge functionality specifically is not detailed as a single operation. The standard endpoints for managing pull requests are: GET /repos/{owner}/{repo}/pulls: Lists pull requests for a repository. GET /repos/{owner}/{repo}/pulls/{pull_number}: Gets a single pull request by its number. Regarding stacks, the GitHub REST API includes functionality to retrieve stack information [1]. You can use the following endpoint to get details about a specific stack: GET /repos/{owner}/{repo}/stacks/{stack_number} There is no standard REST API endpoint explicitly named stack merge. If you are working with stacked pull requests, you typically manage them through individual pull request operations or specialized tools designed for stack workflows [1].
Citations:
Clarify the merge wording
The Stacks API reference doesn’t expose the stack-aware merge behavior used by the web UI; GitHub still has the generic PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge endpoint, so avoid saying REST has no merge operation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/investigations/github-stacked-pr-merge.md` around lines 7 - 15, Update
the investigation wording around the Stacks API to distinguish missing
stack-aware merge behavior from the available generic pull-request merge
operation. Preserve the documented stack endpoints, but explicitly acknowledge
GitHub’s generic PUT pull-request merge endpoint and avoid claiming that REST
has no merge operation.
1 participant
Problem
GitHub Stacked PRs can merge a stack in the web UI, but
gh stackv0.0.8 has no merge command. The preview interfaces need a verified baseline before testing the private web operation.Solution
Add
docs/investigations/github-stacked-pr-merge.mdwith the documented REST endpoints, absent public GraphQL surface, and position-based merge semantics.Test plan
git diff --checkStack 1/2 · created with GitHub Stacks CLI