create stack api

Author: skarim

README.md

@@ -55,7 +55,7 @@ main (trunk)
 
 The **bottom** of the stack is the branch closest to the trunk, and the **top** is the branch furthest from it. Each branch inherits from the one below it. Navigation commands (`up`, `down`, `top`, `bottom`) follow this model: `up` moves away from trunk, `down` moves toward it.
 
-When you push, `gh stack` creates one PR per branch. Each PR's base is set to the branch below it in the stack, so reviewers see only the diff for that layer.
+When you push, `gh stack` creates one PR per branch and links them together as a **Stack** on GitHub. Each PR's base is set to the branch below it in the stack, so reviewers see only the diff for that layer.
 
 ### Local tracking
 
@@ -261,6 +261,8 @@ gh stack push [flags]
 
 Pushes every branch to the remote, then for each branch either creates a new PR (with the correct base branch) or updates the base of an existing PR if it has changed. Uses `--force-with-lease` by default to safely update rebased branches.
 
+After creating PRs, `push` automatically creates a **Stack** on GitHub to link the PRs together. If the stack already exists on GitHub (e.g., from a previous push), it is left as-is — updating existing stacks will be supported in an upcoming release.
+
 When creating new PRs, you will be prompted to enter a title for each one. Press Enter to accept the default (branch name), or use `--auto` to skip prompting entirely.
 
 | Flag | Description |

cmd/push.go

@@ -3,8 +3,10 @@ package cmd
 import (
 	"errors"
 	"fmt"
+	"strconv"
 	"strings"
 
+	"github.com/cli/go-gh/v2/pkg/api"
 	"github.com/cli/go-gh/v2/pkg/prompter"
 	"github.com/github/gh-stack/internal/config"
 	"github.com/github/gh-stack/internal/git"
@@ -165,15 +167,8 @@ func runPush(cfg *config.Config, opts *pushOptions) error {
 		}
 	}
 
-	// TODO: Add PRs to a stack
-	//
-	// We can call an API after all the individual PRs are created/updated to create the stack at once,
-	// or we can add a flag to the existing PR API to incrementally build the stack.
-	//
-	// For now, the PRs are pushed and created individually but are NOT linked as a formal stack on GitHub.
-	cfg.Warningf("Stacked PRs is not yet implemented — PRs were created individually.")
-	fmt.Fprintf(cfg.Err, "  Once the GitHub Stacks API is available, PRs will be automatically\n")
-	fmt.Fprintf(cfg.Err, "  grouped into a Stack.\n")
+	// Create or update the stack on GitHub
+	createStack(cfg, client, s)
 
 	// Update base commit hashes and sync PR state
 	updateBaseSHAs(s)
@@ -261,3 +256,55 @@ func pickRemote(cfg *config.Config, branch, remoteOverride string) (string, erro
 	}
 	return multi.Remotes[selected], nil
 }
+
+// createStack attempts to create a stack on GitHub from the active PRs.
+// It is a best-effort operation: failures are reported as warnings but do
+// not cause the push command to fail (the PRs are already created).
+func createStack(cfg *config.Config, client interface{ CreateStack([]int) (int, error) }, s *stack.Stack) {
+	// Collect PR numbers in stack order (bottom to top).
+	var prNumbers []int
+	for _, b := range s.Branches {
+		if b.IsMerged() {
+			continue
+		}
+		if b.PullRequest != nil {
+			prNumbers = append(prNumbers, b.PullRequest.Number)
+		}
+	}
+
+	// The API requires at least 2 PRs to form a stack.
+	if len(prNumbers) < 2 {
+		return
+	}
+
+	stackID, err := client.CreateStack(prNumbers)
+	if err == nil {
+		s.ID = strconv.Itoa(stackID)
+		cfg.Successf("Stack created on GitHub with %d PRs", len(prNumbers))
+		return
+	}
+
+	cfg.Warningf("Failed to create stack on GitHub: %v", err)
+	var httpErr *api.HTTPError
+	if !errors.As(err, &httpErr) {
+		cfg.Warningf("Failed to create stack on GitHub: %v", err)
+		return
+	}
+
+	cfg.Warningf("error %s with code %s", httpErr.StatusCode, httpErr.Message)
+	switch httpErr.StatusCode {
+	case 422:
+		if s.ID != "" {
+			// Stack was already created in a previous push; the update API
+			// (PUT) is needed to modify it but is not yet available.
+			cfg.Infof("Stack already exists on GitHub")
+		} else {
+			cfg.Warningf("Could not create stack: %s", httpErr.Message)
+			cfg.Printf("  Updating existing stacks will be supported in an upcoming release.")
+		}
+	case 404:
+		cfg.Warningf("Stacked PRs are not enabled for this repository")
+	default:
+		cfg.Warningf("Failed to create stack on GitHub: %s", httpErr.Message)
+	}
+}

cmd/push_test.go

@@ -3,8 +3,10 @@ package cmd
 import (
 	"fmt"
 	"io"
+	"net/url"
 	"testing"
 
+	"github.com/cli/go-gh/v2/pkg/api"
 	"github.com/github/gh-stack/internal/config"
 	"github.com/github/gh-stack/internal/git"
 	"github.com/github/gh-stack/internal/github"
@@ -225,3 +227,195 @@ func TestPush_Humanize(t *testing.T) {
 		})
 	}
 }
+
+func TestCreateStack_Success(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+			{Branch: "b2", PullRequest: &stack.PullRequestRef{Number: 11}},
+		},
+	}
+
+	var gotNumbers []int
+	mock := &github.MockClient{
+		CreateStackFn: func(prNumbers []int) (int, error) {
+			gotNumbers = prNumbers
+			return 42, nil
+		},
+	}
+
+	cfg, _, errR := config.NewTestConfig()
+	createStack(cfg, mock, s)
+
+	cfg.Err.Close()
+	errOut, _ := io.ReadAll(errR)
+	output := string(errOut)
+
+	assert.Equal(t, []int{10, 11}, gotNumbers)
+	assert.Equal(t, "42", s.ID)
+	assert.Contains(t, output, "Stack created on GitHub with 2 PRs")
+}
+
+func TestCreateStack_AlreadyExists_WithLocalID(t *testing.T) {
+	s := &stack.Stack{
+		ID:    "99",
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+			{Branch: "b2", PullRequest: &stack.PullRequestRef{Number: 11}},
+		},
+	}
+
+	mock := &github.MockClient{
+		CreateStackFn: func([]int) (int, error) {
+			return 0, &api.HTTPError{
+				StatusCode: 422,
+				Message:    "Pull requests are already in a stack",
+				RequestURL: &url.URL{Path: "/repos/o/r/cli_internal/pulls/stacks"},
+			}
+		},
+	}
+
+	cfg, _, errR := config.NewTestConfig()
+	createStack(cfg, mock, s)
+
+	cfg.Err.Close()
+	errOut, _ := io.ReadAll(errR)
+	output := string(errOut)
+
+	assert.Contains(t, output, "Stack already exists on GitHub")
+	assert.Equal(t, "99", s.ID)
+}
+
+func TestCreateStack_AlreadyExists_NoLocalID(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+			{Branch: "b2", PullRequest: &stack.PullRequestRef{Number: 11}},
+		},
+	}
+
+	mock := &github.MockClient{
+		CreateStackFn: func([]int) (int, error) {
+			return 0, &api.HTTPError{
+				StatusCode: 422,
+				Message:    "Pull requests are already in a stack",
+				RequestURL: &url.URL{Path: "/repos/o/r/cli_internal/pulls/stacks"},
+			}
+		},
+	}
+
+	cfg, _, errR := config.NewTestConfig()
+	createStack(cfg, mock, s)
+
+	cfg.Err.Close()
+	errOut, _ := io.ReadAll(errR)
+	output := string(errOut)
+
+	assert.Contains(t, output, "Could not create stack")
+	assert.Contains(t, output, "Updating existing stacks will be supported in an upcoming release")
+}
+
+func TestCreateStack_NotAvailable(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+			{Branch: "b2", PullRequest: &stack.PullRequestRef{Number: 11}},
+		},
+	}
+
+	mock := &github.MockClient{
+		CreateStackFn: func([]int) (int, error) {
+			return 0, &api.HTTPError{
+				StatusCode: 404,
+				Message:    "Not Found",
+				RequestURL: &url.URL{Path: "/repos/o/r/cli_internal/pulls/stacks"},
+			}
+		},
+	}
+
+	cfg, _, errR := config.NewTestConfig()
+	createStack(cfg, mock, s)
+
+	cfg.Err.Close()
+	errOut, _ := io.ReadAll(errR)
+	output := string(errOut)
+
+	assert.Contains(t, output, "not yet available")
+}
+
+func TestCreateStack_SkippedForSinglePR(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+		},
+	}
+
+	called := false
+	mock := &github.MockClient{
+		CreateStackFn: func([]int) (int, error) {
+			called = true
+			return 42, nil
+		},
+	}
+
+	cfg, _, _ := config.NewTestConfig()
+	createStack(cfg, mock, s)
+	cfg.Err.Close()
+
+	assert.False(t, called, "CreateStack should not be called with fewer than 2 PRs")
+}
+
+func TestCreateStack_SkipsMergedBranches(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10, Merged: true}},
+			{Branch: "b2", PullRequest: &stack.PullRequestRef{Number: 11}},
+			{Branch: "b3", PullRequest: &stack.PullRequestRef{Number: 12}},
+		},
+	}
+
+	var gotNumbers []int
+	mock := &github.MockClient{
+		CreateStackFn: func(prNumbers []int) (int, error) {
+			gotNumbers = prNumbers
+			return 42, nil
+		},
+	}
+
+	cfg, _, _ := config.NewTestConfig()
+	createStack(cfg, mock, s)
+	cfg.Err.Close()
+
+	assert.Equal(t, []int{11, 12}, gotNumbers, "should only include non-merged PRs")
+}
+
+func TestCreateStack_SkipsBranchesWithoutPR(t *testing.T) {
+	s := &stack.Stack{
+		Trunk: stack.BranchRef{Branch: "main"},
+		Branches: []stack.BranchRef{
+			{Branch: "b1", PullRequest: &stack.PullRequestRef{Number: 10}},
+			{Branch: "b2"}, // no PR yet
+			{Branch: "b3", PullRequest: &stack.PullRequestRef{Number: 12}},
+		},
+	}
+
+	var gotNumbers []int
+	mock := &github.MockClient{
+		CreateStackFn: func(prNumbers []int) (int, error) {
+			gotNumbers = prNumbers
+			return 42, nil
+		},
+	}
+
+	cfg, _, _ := config.NewTestConfig()
+	createStack(cfg, mock, s)
+	cfg.Err.Close()
+
+	assert.Equal(t, []int{10, 12}, gotNumbers, "should skip branches without PRs")
+}

internal/github/client_interface.go

@@ -8,6 +8,7 @@ type ClientOps interface {
 	FindAnyPRForBranch(branch string) (*PullRequest, error)
 	FindPRDetailsForBranch(branch string) (*PRDetails, error)
 	CreatePR(base, head, title, body string, draft bool) (*PullRequest, error)
+	CreateStack(prNumbers []int) (int, error)
 	DeleteStack() error
 }
 

internal/github/github.go

@@ -1,6 +1,8 @@
 package github
 
 import (
+	"bytes"
+	"encoding/json"
 	"fmt"
 
 	"github.com/cli/go-gh/v2/pkg/api"
@@ -270,6 +272,32 @@ func (c *Client) DeleteStack() error {
 	return fmt.Errorf("deleting a stack on GitHub is not yet supported by the API")
 }
 
+// CreateStack creates a stack on GitHub from an ordered list of PR numbers.
+// The PR numbers must be ordered from bottom to top of the stack and must
+// form a valid base-to-head chain. Returns the server-assigned stack ID.
+func (c *Client) CreateStack(prNumbers []int) (int, error) {
+	type createStackRequest struct {
+		PullRequestNumbers []int `json:"pull_request_numbers"`
+	}
+
+	body, err := json.Marshal(createStackRequest{PullRequestNumbers: prNumbers})
+	if err != nil {
+		return 0, fmt.Errorf("marshaling request: %w", err)
+	}
+
+	path := fmt.Sprintf("repos/%s/%s/cli_internal/pulls/stacks", c.owner, c.repo)
+
+	var response struct {
+		ID int `json:"id"`
+	}
+
+	if err := c.rest.Post(path, bytes.NewReader(body), &response); err != nil {
+		return 0, err
+	}
+
+	return response.ID, nil
+}
+
 func (c *Client) repositoryID() (string, error) {
 	var query struct {
 		Repository struct {

internal/github/mock_client.go

@@ -10,6 +10,7 @@ type MockClient struct {
 	FindAnyPRForBranchFn     func(string) (*PullRequest, error)
 	FindPRDetailsForBranchFn func(string) (*PRDetails, error)
 	CreatePRFn    func(string, string, string, string, bool) (*PullRequest, error)
+	CreateStackFn func([]int) (int, error)
 	DeleteStackFn func() error
 }
 
@@ -50,3 +51,10 @@ func (m *MockClient) DeleteStack() error {
 	}
 	return fmt.Errorf("deleting a stack on GitHub is not yet supported by the API")
 }
+
+func (m *MockClient) CreateStack(prNumbers []int) (int, error) {
+	if m.CreateStackFn != nil {
+		return m.CreateStackFn(prNumbers)
+	}
+	return 0, nil
+}

skills/gh-stack/SKILL.md

@@ -489,6 +489,7 @@ gh stack push --skip-prs
 
 - Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`)
 - Creates a new PR for each branch that doesn't have one (base set to the first non-merged ancestor branch)
+- After creating PRs, links them together as a **Stack** on GitHub (requires the repository to have stacks enabled)
 - Syncs PR metadata for branches that already have PRs
 
 **PR title auto-generation (`--auto`):**