feat: Add stacked pull request endpoints by Bortlesboat · Pull Request #4436 · google/go-github

Bortlesboat · 2026-08-06T17:28:52Z

Add typed PullRequestsService support for GitHub's five stacked pull request
REST endpoints:

list repository stacks, optionally filtered by pull request;
create and get a stack;
append pull requests to a stack; and
unstack the remaining unmerged pull requests.

The change keeps pull-request membership metadata separate from the endpoint
stack resource, adds typed request and list-option types, handles both
updated-stack and 204 No Content unstack responses, and regenerates accessors
and iterators. Request methods,
paths, query parameters, bodies, response decoding, and failure paths have
focused coverage.

API contract: https://docs.github.com/en/rest/pulls/stacks?apiVersion=2022-11-28

Validation:

script/fmt.sh
script/lint.sh across all 12 modules
script/test.sh -covermode atomic ./... across all 12 modules
git diff --check

The local Go configuration has CGO disabled, so a race build was not available;
the full non-race suite passed.

AI assistance: OpenAI Codex helped draft the API bindings, tests, generated-file
workflow, and PR description. I reviewed the rendered diff and validation
evidence, understand every submitted line, and take responsibility for the
contribution and review follow-up.

codecov · 2026-08-06T23:55:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.56%. Comparing base (4a79475) to head (5ad53ca).
⚠️ Report is 6 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4436   +/-   ##
=======================================
  Coverage   97.55%   97.56%           
=======================================
  Files         194      195    +1     
  Lines       19892    19962   +70     
=======================================
+ Hits        19406    19476   +70     
  Misses        268      268           
  Partials      218      218

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

gmlewis

Thank you, @Bortlesboat!
LGTM.
Awaiting second LGTM+Approval from any other contributor to this repo before merging.

cc: @stevehipwell - @alexandear - @Not-Dhananjay-Mishra

Bortlesboat · 2026-08-07T17:17:06Z

All three review items are addressed in signed commit 295dd70, and their threads are resolved. Local script/test.sh -covermode atomic ./..., script/lint.sh, script/fmt.sh, and script/generate.sh --check all pass. GitHub initially held the new tests, linter, and workflow-security runs at action_required; a maintainer approved them, and the full current upstream matrix is now green.

Not-Dhananjay-Mishra · 2026-08-08T03:24:27Z

+type PullRequestStackDetails struct {
+	// ID is the ID of the stack.
+	ID *int64 `json:"id,omitempty"`
+	// Number is the number of the stack.
+	Number *int `json:"number,omitempty"`
+	// NodeID is the global node ID of the stack.
+	NodeID *string `json:"node_id,omitempty"`
+	// URL is the API URL of the stack.
+	URL *string `json:"url,omitempty"`
+	// Base is the branch the entire stack ultimately targets.
+	Base *PullRequestStackBase `json:"base"`
+	// Open reports whether the stack contains any open pull requests.
+	Open *bool `json:"open,omitempty"`
+	// CreatedAt is the time the stack was created.
+	CreatedAt *Timestamp `json:"created_at,omitempty"`
+	// PullRequests contains the pull requests in the stack, from bottom to top.
+	PullRequests []*PullRequest `json:"pull_requests,omitempty"`
+}


Suggested change

type PullRequestStackDetails struct {

// ID is the ID of the stack.

ID *int64 `json:"id,omitempty"`

// Number is the number of the stack.

Number *int `json:"number,omitempty"`

// NodeID is the global node ID of the stack.

NodeID *string `json:"node_id,omitempty"`

// URL is the API URL of the stack.

URL *string `json:"url,omitempty"`

// Base is the branch the entire stack ultimately targets.

Base *PullRequestStackBase `json:"base"`

// Open reports whether the stack contains any open pull requests.

Open *bool `json:"open,omitempty"`

// CreatedAt is the time the stack was created.

CreatedAt *Timestamp `json:"created_at,omitempty"`

// PullRequests contains the pull requests in the stack, from bottom to top.

PullRequests []*PullRequest `json:"pull_requests,omitempty"`

}

type PullRequestStackDetails struct {

// ID is the ID of the stack.

ID int64 `json:"id"`

// Number is the number of the stack.

Number int `json:"number"`

// NodeID is the global node ID of the stack.

NodeID string `json:"node_id"`

// URL is the API URL of the stack.

URL string `json:"url"`

// Base is the branch the entire stack ultimately targets.

Base *PullRequestStackBase `json:"base"`

// Open reports whether the stack contains any open pull requests.

Open bool `json:"open"`

// CreatedAt is the time the stack was created.

CreatedAt Timestamp `json:"created_at"`

// PullRequests contains the pull requests in the stack, from bottom to top.

PullRequests []*PullRequest `json:"pull_requests"`

}

All fields are required according to response schema and we don't use ,omitempty with required field CONTRIBUTING.md

"title": "Pull Request Stack Minimal", "type": "object", "required": [ "id", "number", "node_id", "url", "base", "open", "created_at", "pull_requests" ],

Not-Dhananjay-Mishra · 2026-08-08T03:33:30Z

+	// URL is the API URL of the stack.
+	URL *string `json:"url,omitempty"`
+	// Base is the branch the entire stack ultimately targets.
+	Base *PullRequestStackBase `json:"base"`


PullRequestStackBase has one extra field sha which is not present in response schema. so let's implement a new struct instead.

// PullRequestStackBase represents the base of a stacked pull request's stack: // the branch the entire stack ultimately targets. type PullRequestStackBase struct { Ref string `json:"ref"` SHA string `json:"sha"` }

response schema

"base": { "type": "object", "required": [ "ref" ], "properties": { "ref": { "type": "string" } } }

Not-Dhananjay-Mishra · 2026-08-08T03:43:46Z

+// GitHub API docs: https://docs.github.com/rest/pulls/stacks?apiVersion=2022-11-28#list-pull-request-stacks
+//
+//meta:operation GET /repos/{owner}/{repo}/stacks
+func (s *PullRequestsService) ListStacks(ctx context.Context, owner, repo string, opts *PullRequestListStacksOptions) ([]*PullRequestStackDetails, *Response, error) {


Response schema of List pull request stacks and Create a pull request stack ... differ slightly.
pull_requests object in the List pull request stacks response contains fewer fields than the response from the other endpoint. So we can't use []*PullRequestStackDetails here.

Bortlesboat · 2026-08-08T07:18:02Z

Thanks, both differences check out against the OpenAPI description. Pushed 5ad53ca.

base is {ref} only on all five stack endpoints, so it no longer reuses
PullRequestStackBase — that type stays as-is for PullRequest.Stack, where
base really is {ref, sha}. The stack endpoints now use a new
PullRequestStackRef.

On the list endpoint: the difference is in pull_requests. List items are
{number, state, draft, merged_at, head{ref, sha}}, while create/get/add/unstack
return Pull Request Stack Pull Request, which is Pull Request Minimal
(id, number, url, head/base with a nested repo) plus node_id,
title, state, merged_at, draft, html_url, and user. So ListStacks
now returns []*PullRequestStackMinimal and the other four return
*PullRequestStackDetails. The head/base shapes differ too (list has no
repo), hence the separate branch types.

Also dropped omitempty and the pointers on the required fields per your other
comment. The old test fixture was sending the list-shaped pull_requests for
every endpoint, so there are two fixtures now.

Not-Dhananjay-Mishra

A few struct name suggestions.

Not-Dhananjay-Mishra · 2026-08-08T08:57:47Z

+}
+
+// CreatePullRequestStackRequest represents a request to create a pull request stack.
+type CreatePullRequestStackRequest struct {


Suggested change

type CreatePullRequestStackRequest struct {

type PullRequestCreateStackRequest struct {

I believe this would be better name

Not-Dhananjay-Mishra · 2026-08-08T08:58:01Z

+}
+
+// AddPullRequestsToStackRequest represents a request to append pull requests to a stack.
+type AddPullRequestsToStackRequest struct {


Suggested change

type AddPullRequestsToStackRequest struct {

type PullRequestsAddToStackRequest struct {

Not-Dhananjay-Mishra · 2026-08-08T09:01:32Z

+
+// PullRequestStackPullRequest represents a pull request in a stack returned by
+// PullRequestsService.CreateStack, GetStack, AddToStack, and Unstack.
+type PullRequestStackPullRequest struct {


How is StackPullRequest? PullRequestStackPullRequest feels repetitive.

Suggested change

type PullRequestStackPullRequest struct {

type StackPullRequest struct {

Not-Dhananjay-Mishra · 2026-08-08T09:06:21Z

+
+// PullRequestStackMinimalPullRequest represents a pull request in a stack
+// returned by PullRequestsService.ListStacks.
+type PullRequestStackMinimalPullRequest struct {


How is StackMinimalPullRequest? PullRequestStackMinimalPullRequest feels repetitive.

Suggested change

type PullRequestStackMinimalPullRequest struct {

type StackMinimalPullRequest struct {

Not-Dhananjay-Mishra · 2026-08-08T09:13:07Z

+
+// PullRequestStackMinimalBranch represents the head branch of a pull request
+// returned by PullRequestsService.ListStacks.
+type PullRequestStackMinimalBranch struct {


Suggested change

type PullRequestStackMinimalBranch struct {

type PullRequestStackHead struct {

github: add stacked pull request endpoints

b89249d

gmlewis changed the title ~~github: add stacked pull request endpoints~~ feat: Add stacked pull request endpoints Aug 6, 2026

gmlewis added the NeedsReview PR is awaiting a review before merging. label Aug 6, 2026

gmlewis approved these changes Aug 7, 2026

View reviewed changes

Not-Dhananjay-Mishra reviewed Aug 7, 2026

View reviewed changes

Comment thread github/pulls.go Outdated

Comment thread github/pulls_stacks_test.go Outdated

Comment thread github/pulls_stacks_test.go Outdated

Not-Dhananjay-Mishra mentioned this pull request Aug 7, 2026

fix: Adjust argument index for Fprintf in fmtpercentv linter check #4443

Merged

Split pull request stack response types

295dd70

Not-Dhananjay-Mishra reviewed Aug 8, 2026

View reviewed changes

Align stack response types with response schemas

5ad53ca

Not-Dhananjay-Mishra reviewed Aug 8, 2026

View reviewed changes

	type CreatePullRequestStackRequest struct {
	type PullRequestCreateStackRequest struct {

	type AddPullRequestsToStackRequest struct {
	type PullRequestsAddToStackRequest struct {

	type PullRequestStackPullRequest struct {
	type StackPullRequest struct {

	type PullRequestStackMinimalPullRequest struct {
	type StackMinimalPullRequest struct {

	type PullRequestStackMinimalBranch struct {
	type PullRequestStackHead struct {

Uh oh!

Conversation

Bortlesboat commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Bortlesboat commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bortlesboat commented Aug 8, 2026

Uh oh!

Not-Dhananjay-Mishra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Bortlesboat commented Aug 6, 2026 •

edited

Loading

codecov Bot commented Aug 6, 2026 •

edited

Loading

Bortlesboat commented Aug 7, 2026 •

edited

Loading