github

Documentation

Overview

Package github provides GitHub API integration for gh-stack.

internal/github/github.go

Index

• Constants
• func CollectPRNumbers(root *tree.Node) []int
• func CreatePR(head, base, title, body string) (int, error)
• func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string, prInfo map[int]PRInfo, ...) string
• func UpdatePRBase(number int, base string) error
• type Client
  • func NewClient() (*Client, error)
  • func NewClientWithREST(rest RESTClient, owner, repo string) *Client
  • func (c *Client) CreateComment(prNumber int, body string) (int, error)
  • func (c *Client) CreateDraftPR(head, base, title, body string) (int, error)
  • func (c *Client) CreateOrUpdateStackComment(prNumber int, body string) error
  • func (c *Client) CreatePR(head, base, title, body string) (int, error)
  • func (c *Client) CreateSubmitPR(head, base, title, body string, draft bool) (*PR, error)
  • func (c *Client) FindPRByHead(branch string) (*PR, error)
  • func (c *Client) FindStackComment(prNumber int) (int, string, error)
  • func (c *Client) GenerateAndPostStackComment(root *tree.Node, branch, trunk string, prNumber int, ...) error
  • func (c *Client) GetPR(number int) (*PR, error)
  • func (c *Client) GetPRTitles(prNumbers []int) (map[int]PRInfo, error)
  • func (c *Client) ListComments(prNumber int) ([]Comment, error)
  • func (c *Client) MarkPRReady(prNumber int) error
  • func (c *Client) PRURL(number int) string
  • func (c *Client) RepoURL() string
  • func (c *Client) UpdateComment(commentID int, body string) error
  • func (c *Client) UpdatePRBase(number int, base string) error
• type Comment
• type PR
  • func GetPR(number int) (*PR, error)
• type PRInfo
• type RESTClient

Constants

const StackCommentMarker = "<!-- gh-stack:nav -->"

StackCommentMarker identifies gh-stack managed comments.

Functions

func CollectPRNumbers

func CollectPRNumbers(root *tree.Node) []int

CollectPRNumbers walks a tree and returns all PR numbers found.

func CreatePR

func CreatePR(head, base, title, body string) (int, error)

CreatePR creates a new pull request using the default client.

Deprecated: Use NewClient() and call methods directly for better error handling.

func GenerateStackComment

func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string, prInfo map[int]PRInfo, remoteBranches map[string]bool) string

GenerateStackComment builds markdown for a PR's stack position. It includes a warning if the PR targets a non-trunk branch. The repoURL should be the base repository URL (e.g., "https://github.com/owner/repo"). The prInfo map provides titles for PRs (keyed by PR number).

Only the current stack is rendered: the path from root to the current branch, plus all descendants of the current branch. Sibling stacks are excluded.

If remoteBranches is non-nil, branches without PRs that don't exist on the remote are omitted (their children are promoted up a level). Pass nil to disable this filtering.

func UpdatePRBase

func UpdatePRBase(number int, base string) error

UpdatePRBase updates the base branch using the default client.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps a REST client with repo context.

func NewClient

func NewClient() (*Client, error)

NewClient creates a new GitHub client for the current repository.

func NewClientWithREST

func NewClientWithREST(rest RESTClient, owner, repo string) *Client

NewClientWithREST creates a client with a custom REST implementation. This is primarily useful for testing.

func (*Client) CreateComment

func (c *Client) CreateComment(prNumber int, body string) (int, error)

CreateComment adds a comment to a PR (PRs are issues in GitHub's API).

func (*Client) CreateDraftPR

func (c *Client) CreateDraftPR(head, base, title, body string) (int, error)

CreateDraftPR creates a new pull request as a draft.

func (*Client) CreateOrUpdateStackComment

func (c *Client) CreateOrUpdateStackComment(prNumber int, body string) error

CreateOrUpdateStackComment finds an existing stack comment by marker and updates it, or creates a new one if none exists. Skips the update if the body hasn't changed.

func (*Client) CreatePR

func (c *Client) CreatePR(head, base, title, body string) (int, error)

CreatePR creates a new pull request and returns the PR number.

func (*Client) CreateSubmitPR

func (c *Client) CreateSubmitPR(head, base, title, body string, draft bool) (*PR, error)

CreateSubmitPR creates a new pull request. This is the primary method for the submit workflow. If draft is true, creates a draft PR. The body parameter is used as the PR description; pass an empty string for no description.

func (*Client) FindPRByHead

func (c *Client) FindPRByHead(branch string) (*PR, error)

FindPRByHead finds an open PR with the given head branch. Returns nil, nil if no PR exists for this branch.

func (*Client) FindStackComment

func (c *Client) FindStackComment(prNumber int) (int, string, error)

FindStackComment searches for an existing gh-stack comment on a PR. Returns the comment ID and body if found, or (0, "") if not found.

func (*Client) GenerateAndPostStackComment

func (c *Client) GenerateAndPostStackComment(root *tree.Node, branch, trunk string, prNumber int, remoteBranches map[string]bool) error

GenerateAndPostStackComment generates and posts/updates a stack comment for a PR. It fetches PR titles via GraphQL and renders the full comment.

If remoteBranches is non-nil, branches without PRs that don't exist on the remote are omitted from the rendered comment. Pass nil to disable filtering.

func (*Client) GetPR

func (c *Client) GetPR(number int) (*PR, error)

GetPR fetches PR details by number.

func (*Client) GetPRTitles

func (c *Client) GetPRTitles(prNumbers []int) (map[int]PRInfo, error)

GetPRTitles fetches titles for multiple PRs in a single GraphQL request. Returns a map of PR number to PRInfo. PRs that don't exist are omitted.

Note: This builds a single GraphQL query with all PR requests. For extremely large stacks (100+ PRs), this could potentially hit query size limits. In practice, stacks rarely exceed 10-20 PRs, so batching is not implemented.

func (*Client) ListComments

func (c *Client) ListComments(prNumber int) ([]Comment, error)

ListComments retrieves all comments on a PR.

func (*Client) MarkPRReady

func (c *Client) MarkPRReady(prNumber int) error

MarkPRReady converts a draft PR to ready for review. Uses the GraphQL API since REST doesn't support this operation.

func (*Client) PRURL

func (c *Client) PRURL(number int) string

PRURL returns the web URL for a pull request.

func (*Client) RepoURL

func (c *Client) RepoURL() string

RepoURL returns the base URL for the repository (e.g., "https://github.com/owner/repo").

func (*Client) UpdateComment

func (c *Client) UpdateComment(commentID int, body string) error

UpdateComment updates an existing comment by ID.

func (*Client) UpdatePRBase

func (c *Client) UpdatePRBase(number int, base string) error

UpdatePRBase updates the base branch of a PR.

type Comment

type Comment struct {
	ID   int    `json:"id"`
	Body string `json:"body"`
}

Comment represents a GitHub issue/PR comment.

type PR

type PR struct {
	Number int    `json:"number"`
	Title  string `json:"title"`
	State  string `json:"state"`
	Merged bool   `json:"merged"`
	Draft  bool   `json:"draft"`
	Base   struct {
		Ref string `json:"ref"`
	} `json:"base"`
}

PR represents a GitHub pull request.

func GetPR

func GetPR(number int) (*PR, error)

GetPR fetches PR details using the default client.

type PRInfo

type PRInfo struct {
	Number int
	Title  string
}

PRInfo contains display information for a PR in stack comments.

type RESTClient

type RESTClient interface {
	Get(path string, response any) error
	Post(path string, body io.Reader, response any) error
	Patch(path string, body io.Reader, response any) error
}

RESTClient defines the interface for GitHub REST API operations. The *api.RESTClient from go-gh satisfies this interface.