Help us shape the future of Go! Take the 2026 Go Developer Survey

github

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 25, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MergeMethodMerge  = "merge"
	MergeMethodSquash = "squash"
	MergeMethodRebase = "rebase"
)

Merge method values accepted by the async merge REST API.

View Source 
const (
	MergeActionDefault     = "default"
	MergeActionDirectMerge = "direct_merge"
	MergeActionMergeQueue  = "merge_queue"
)

Merge action values for the async merge API's merge_action field. "default" lets the server choose between a direct merge and the base branch's merge queue; "direct_merge" and "merge_queue" force the respective path. Sending an explicit action makes the caller's merge-queue detection authoritative: the server rejects "merge_queue" on a branch with no queue rather than silently merging directly.

View Source 
const (
	AsyncMergeStatusPending  = "pending"
	AsyncMergeStatusMerged   = "merged"
	AsyncMergeStatusEnqueued = "enqueued"
	AsyncMergeStatusFailed   = "failed"
)

Async merge status values returned in the response's "status" field.

Variables

View Source 
var ErrAsyncMergeUnavailable = errors.New("async stack merge is not available for this repository")

ErrAsyncMergeUnavailable indicates the async merge API is not available for the repository (or the token lacks access). Surfaced on a 404 from the submit endpoint.

View Source 
var Info = protocol.Info{
	Name:         "github",
	Terms:        protocol.Terms{Short: "PR", Long: "pull request", Ref: "#%d"},
	MergeMethods: []string{protocol.MethodMerge, protocol.MethodSquash, protocol.MethodRebase},
	NativeStacks: true,
}

Info describes the GitHub provider.

Functions

func PRURL 

func PRURL(host, owner, repo string, number int) string

PRURL constructs the web URL for a pull request on the given host.

func Plugin 

func Plugin(opts api.ClientOptions) protocol.Plugin

Plugin is the GitHub provider plugin, for protocol.Serve. opts carries test overrides (Transport, AuthToken); the host comes from the repository.

func StackURL 

func StackURL(host, owner, repo string, number int) string

StackURL constructs the web URL for a repository-scoped stack number.

Types

type AsyncMergeDetails 

type AsyncMergeDetails struct {
	Message         string `json:"message"`
	UUID            string `json:"uuid"`
	MergeMethod     string `json:"merge_method"`
	MergeAction     string `json:"merge_action"`
	ExpectedHeadSHA string `json:"expected_head_sha"`
	SHA             string `json:"sha"`
}

AsyncMergeDetails is the polymorphic "details" object shared by the submit and poll responses. Fields are populated based on the current state: a pending request carries UUID/MergeMethod/MergeAction/ExpectedHeadSHA, a merged result carries SHA, and a failed/not-mergeable result carries only Message.

type AsyncMergeResult 

type AsyncMergeResult struct {
	Status  string            `json:"status"`
	Details AsyncMergeDetails `json:"details"`
}

AsyncMergeResult is the response body returned by both the submit and poll async merge endpoints. Status is one of the AsyncMergeStatus* values: "pending" (running in the background), "merged" (merged directly), "enqueued" (added to the base branch's merge queue), or "failed".

func (*AsyncMergeResult) IsEnqueued 

func (r *AsyncMergeResult) IsEnqueued() bool

IsEnqueued reports whether the stack was added to the base branch's merge queue (it will merge once the queue processes it).

func (*AsyncMergeResult) IsFailed 

func (r *AsyncMergeResult) IsFailed() bool

IsFailed reports whether the merge was attempted but did not complete.

func (*AsyncMergeResult) IsMerged 

func (r *AsyncMergeResult) IsMerged() bool

IsMerged reports whether the merge completed successfully.

func (*AsyncMergeResult) IsPending 

func (r *AsyncMergeResult) IsPending() bool

IsPending reports whether the merge is still running in the background.

type AutoMergeRequest 

type AutoMergeRequest struct {
	EnabledAt string `graphql:"enabledAt"`
}

AutoMergeRequest represents an auto-merge configuration on a PR. When the GraphQL field autoMergeRequest is null (auto-merge not enabled), the pointer will be nil.

type Client 

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

Client wraps GitHub API operations.

func NewClient 

func NewClient(host, owner, repo string) (*Client, error)

NewClient creates a new GitHub API client for the given repository. The host parameter specifies the GitHub hostname (e.g. "github.com" or a GHES hostname like "github.mycompany.com"). If empty, it defaults to "github.com".

func (*Client) AddToStack 

func (c *Client) AddToStack(stackNumber int, prNumbers []int) (*RemoteStack, error)

AddToStack appends pull requests to the top of an existing stack. Only the new PR numbers (the delta) should be provided, ordered from the current top of the stack upward. Returns the updated stack.

func (*Client) BaseBranchUsesMergeQueue 

func (c *Client) BaseBranchUsesMergeQueue(baseRef string) (bool, error)

BaseBranchUsesMergeQueue reports whether the given base branch merges through a merge queue, detected via the branch's merge queue object or a MERGE_QUEUE repository rule. It is used only to tailor the merge wizard (skipping the merge-method step and switching to "enqueue" wording): the async stack merge itself always sends merge_action "default", which lets the server route the stack to the queue or a direct merge automatically.

func (*Client) CreatePR 

func (c *Client) CreatePR(base, head, title, body string, draft bool) (*PullRequest, error)

CreatePR creates a new pull request.

func (*Client) CreateStack 

func (c *Client) CreateStack(prNumbers []int) (*RemoteStack, error)

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 (at least two) and must form a valid base-to-head chain. Returns the created stack.

func (*Client) DisableAutoMerge 

func (c *Client) DisableAutoMerge(prID string) error

DisableAutoMerge disables auto-merge on a pull request.

func (*Client) FindPRByNumber 

func (c *Client) FindPRByNumber(number int) (*PullRequest, error)

FindPRByNumber fetches a pull request by its number.

func (*Client) FindPRDetailsForBranch 

func (c *Client) FindPRDetailsForBranch(branch string) (*PRDetails, error)

FindPRDetailsForBranch fetches enriched PR data for display purposes. Returns nil without error if no PR exists for the branch.

func (*Client) FindPRForBranch 

func (c *Client) FindPRForBranch(branch string) (*PullRequest, error)

FindPRForBranch finds an open PR by head branch name.

func (*Client) FindStackForPR 

func (c *Client) FindStackForPR(prNumber int) (*RemoteStack, error)

FindStackForPR returns the stack that contains the given pull request number, using the list endpoint's server-side pull_request filter. Returns nil (without error) when the PR is not part of any stack.

func (*Client) GetAsyncMergeResult 

func (c *Client) GetAsyncMergeResult(prNumber int, uuid string) (*AsyncMergeResult, error)

GetAsyncMergeResult fetches the current result of a previously submitted async merge, identified by the UUID returned from MergeStackAsync. A valid lookup always returns 200, so the wrapped status/details reflect the merge's progress (pending, merged, enqueued, or failed).

func (*Client) GetStack 

func (c *Client) GetStack(stackNumber int) (*RemoteStack, error)

GetStack fetches a single stack by its stack number.

func (*Client) ListStacks 

func (c *Client) ListStacks() ([]RemoteStack, error)

ListStacks returns all stacks in the repository, ordered by stack number (descending). Returns an empty slice if no stacks exist. A 404 response indicates stacked PRs are not enabled for this repository.

func (*Client) MarkPRReadyForReview 

func (c *Client) MarkPRReadyForReview(prID string) error

MarkPRReadyForReview converts a draft pull request to ready for review.

func (*Client) MergeStackAsync 

func (c *Client) MergeStackAsync(prNumber int, method, mergeAction string) (*AsyncMergeResult, error)

MergeStackAsync requests an asynchronous merge of the given pull request. For a stacked PR this merges all members of the stack up to and including prNumber. A blank method lets the server apply its default.

mergeAction selects the routing: MergeActionDirectMerge or MergeActionMergeQueue force the respective path, and MergeActionDefault (also the fallback for an empty value) lets the server choose. Sending an explicit action makes the caller's merge-queue detection authoritative — the server rejects "merge_queue" on a branch with no queue instead of silently merging directly.

On success the returned result is populated for the 200 (already merged) and 202 (enqueued for background processing) responses. A 404 returns ErrAsyncMergeUnavailable, a 409 (a request already exists) returns a clear "already exists" error, and any other non-2xx status is returned as-is.

func (*Client) PRTitles 

func (c *Client) PRTitles(numbers []int) (map[int]string, error)

PRTitles fetches the titles for a set of pull request numbers in a single GraphQL query. Missing PRs are simply absent from the result. Best-effort: callers may ignore the error and proceed without titles.

func (*Client) RepoMergeConfig 

func (c *Client) RepoMergeConfig() (*RepoMergeConfig, error)

RepoMergeConfig fetches the repository's allowed merge methods and the viewer's default (last-used) merge method.

func (*Client) Unstack 

func (c *Client) Unstack(stackNumber int) (rs *RemoteStack, dissolved bool, err error)

Unstack removes eligible pull requests from a stack. When PRs remain (e.g. merged or queued PRs), the updated stack is returned with dissolved=false. When none remain, the stack is destroyed and dissolved=true (HTTP 204). Both outcomes indicate a successful unstack.

func (*Client) UpdatePRBase 

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

UpdatePRBase updates the base branch of an existing pull request.

type MergeQueueEntry 

type MergeQueueEntry struct {
	ID string `graphql:"id"`
}

MergeQueueEntry represents a merge queue entry. When the GraphQL field mergeQueueEntry is null (PR not queued), the pointer will be nil.

type PRDetails 

type PRDetails struct {
	Number   int
	State    string // OPEN, CLOSED, MERGED
	URL      string
	Title    string
	Body     string
	IsDraft  bool
	Merged   bool
	IsQueued bool
}

PRDetails holds enriched pull request data for display in the TUI.

type Provider 

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

Provider adapts Client to protocol.Provider.

func (*Provider) CancelAutoMerge 

func (p *Provider) CancelAutoMerge(number int) error

CancelAutoMerge turns auto-merge off.

func (*Provider) CreateCR 

func (p *Provider) CreateCR(n protocol.NewCR) (*protocol.CR, error)

CreateCR opens a pull request.

func (*Provider) FindCRForBranch 

func (p *Provider) FindCRForBranch(branch string) (*protocol.CR, error)

FindCRForBranch returns the open PR whose head is branch, else the most recently merged one, else nil. PRs from forks are ignored.

func (*Provider) GetBranch 

func (p *Provider) GetBranch(name string) (*protocol.Branch, error)

GetBranch fetches branch protection and whether name is the default branch.

func (*Provider) GetCR 

func (p *Provider) GetCR(number int) (*protocol.CR, error)

GetCR fetches a pull request.

func (*Provider) GetRepo 

func (p *Provider) GetRepo() (*protocol.RepoSettings, error)

GetRepo returns the viewer's default merge method for the repository.

func (*Provider) ListCRsTargeting 

func (p *Provider) ListCRsTargeting(branch string) ([]*protocol.CR, error)

ListCRsTargeting returns open PRs, not from forks, whose base is branch.

func (*Provider) MarkReady 

func (p *Provider) MarkReady(number int) (*protocol.CR, error)

MarkReady takes a pull request out of draft.

func (*Provider) Merge 

func (p *Provider) Merge(number int, method, sha string) (*protocol.CR, error)

Merge merges the pull request at sha. When GitHub refuses a direct merge (checks pending, reviews required, merge queue), it enables auto-merge instead, so the PR merges, or joins the queue, once the rules are met. A PR in a native stack goes through the async merge endpoint instead.

func (*Provider) SearchCRs 

func (p *Provider) SearchCRs(text string) ([]*protocol.CR, error)

SearchCRs returns open PRs whose body contains text. GitHub's search does not reliably index text in HTML comments, so open PRs are filtered here.

func (*Provider) SyncStack 

func (p *Provider) SyncStack(numbers []int) error

SyncStack makes GitHub's native stack hold exactly numbers (the open PRs, bottom first). A stack needs at least two PRs; an existing stack whose open PRs are a prefix of numbers is extended, any other is replaced.

func (*Provider) Unstack 

func (p *Provider) Unstack(numbers []int) error

Unstack dissolves the native stack that holds the first of numbers.

func (*Provider) UpdateCR 

func (p *Provider) UpdateCR(number int, u protocol.Update) (*protocol.CR, error)

UpdateCR changes the base, title or body.

type PullRequest 

type PullRequest struct {
	ID               string            `graphql:"id"`
	Number           int               `graphql:"number"`
	State            string            `graphql:"state"`
	URL              string            `graphql:"url"`
	Title            string            `graphql:"title"`
	Body             string            `graphql:"body"`
	HeadRefName      string            `graphql:"headRefName"`
	BaseRefName      string            `graphql:"baseRefName"`
	IsDraft          bool              `graphql:"isDraft"`
	Merged           bool              `graphql:"merged"`
	MergeQueueEntry  *MergeQueueEntry  `graphql:"mergeQueueEntry"`
	AutoMergeRequest *AutoMergeRequest `graphql:"autoMergeRequest"`
}

PullRequest represents a GitHub pull request.

func (*PullRequest) IsAutoMergeEnabled 

func (pr *PullRequest) IsAutoMergeEnabled() bool

IsAutoMergeEnabled reports whether the pull request has auto-merge enabled.

func (*PullRequest) IsQueued 

func (pr *PullRequest) IsQueued() bool

IsQueued reports whether the pull request is currently in a merge queue.

type RemoteStack 

type RemoteStack struct {
	ID           int             `json:"id"`
	Number       int             `json:"number"`
	NodeID       string          `json:"node_id"`
	URL          string          `json:"url"`
	Base         RemoteStackBase `json:"base"`
	Open         bool            `json:"open"`
	CreatedAt    string          `json:"created_at"`
	PullRequests []int           `json:"-"`
	PRDetails    []RemoteStackPR `json:"-"`
}

RemoteStack represents a stack of pull requests as returned by the public Stacks REST API (GET/POST /repos/{owner}/{repo}/stacks...). ID is the internal identifier; Number is the human-facing stack number shown in the github.com UI and used to address the stack in API paths.

The API returns pull_requests as an array of objects; UnmarshalJSON flattens them to the ordered PullRequests numbers (bottom to top) and preserves the full entries in PRDetails for callers that need head refs or PR state.

func (*RemoteStack) PRNumbers 

func (s *RemoteStack) PRNumbers() []int

PRNumbers returns the ordered pull request numbers in the stack, from bottom to top.

func (*RemoteStack) UnmarshalJSON 

func (s *RemoteStack) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the Stacks REST API representation, deriving the ordered PullRequests numbers from the pull_requests objects.

type RemoteStackBase 

type RemoteStackBase struct {
	Ref string `json:"ref"`
	Sha string `json:"sha,omitempty"`
}

RemoteStackBase describes the base ref (and optionally SHA) of a stack.

type RemoteStackPR 

type RemoteStackPR struct {
	Number   int               `json:"number"`
	State    string            `json:"state"` // open, closed
	Draft    bool              `json:"draft"`
	MergedAt *string           `json:"merged_at"`
	Head     RemoteStackPRHead `json:"head"`
}

RemoteStackPR is a pull request entry within a remote stack, as returned by the Stacks REST API list/detail endpoints.

func (RemoteStackPR) IsMerged 

func (p RemoteStackPR) IsMerged() bool

IsMerged reports whether the pull request has been merged.

type RemoteStackPRHead 

type RemoteStackPRHead struct {
	Ref string `json:"ref"`
	Sha string `json:"sha"`
}

RemoteStackPRHead describes the head ref of a pull request in a stack.

type RepoMergeConfig 

type RepoMergeConfig struct {
	MergeAllowed  bool
	SquashAllowed bool
	RebaseAllowed bool
	// DefaultMethod is the viewer's last-used merge method, or the repository
	// default, as one of MergeMethodMerge/MergeMethodSquash/MergeMethodRebase.
	DefaultMethod string
}

RepoMergeConfig describes which merge methods a repository allows, along with the viewer's default (last-used) merge method.

func (RepoMergeConfig) AllowedMethods 

func (c RepoMergeConfig) AllowedMethods() []string

AllowedMethods returns the enabled merge methods in display order (merge, squash, rebase).

func (RepoMergeConfig) Allows 

func (c RepoMergeConfig) Allows(method string) bool

Allows reports whether the given merge method is enabled for the repository.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.