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

github

package
v0.0.0-...-3d73ba5 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package github reads one pull request's metadata, commits, checks and conversation from GitHub's GraphQL API with the user's own token, and maps them onto the generation bundle the way every baum host does. It is the only part of baum that calls GitHub's API. Hosts, repositories, SSH aliases and tokens are read as the GitHub CLI reads them, through its library go-gh; the GraphQL requests are baum's own, over shurcooL-graphql.

Index

Constants

View Source
const (
	SourcePullRequest        = "pull_request"
	SourceRequestedReviewers = "requested_reviewers"
	SourceCommits            = "commits"
	SourceComments           = "comments"
	SourceReviews            = "reviews"
	SourceReviewThreads      = "review_threads"
	SourceChecks             = "checks"
	SourceRequiredChecks     = "required_checks"

	UnavailableReviewComments = "review_comments"
)

The bundle sources a fetch records, one per part read from GitHub. A part is true when GitHub returned all of it, even when that is nothing. Review comments are read with the review threads, so they have no source of their own: when the threads fail, Unavailable says so under UnavailableReviewComments.

Variables

View Source
var (
	// ErrNoRemote reports a clone without an origin remote and no --repo.
	ErrNoRemote = errors.New("this clone has no origin remote; pass --repo owner/name")
	// ErrDetachedHead reports a detached HEAD and no --pr.
	ErrDetachedHead = errors.New("HEAD is detached, so there is no branch to find a pull request for; pass --pr")
	// ErrNoPullRequest reports a branch GitHub knows no pull request for.
	ErrNoPullRequest = errors.New("no pull request found for the current branch; pass --pr")
	// ErrAmbiguousPullRequest reports a branch with several open pull
	// requests.
	ErrAmbiguousPullRequest = errors.New("the current branch has several open pull requests; pass --pr")
)
View Source
var ErrHeadMoved = errors.New("the pull request's head changed while it was being read from GitHub")

ErrHeadMoved reports a pull request whose head changed while it was being read, every time it was read.

View Source
var ErrInvalidRepository = errors.New("--repo must be owner/name, or host/owner/name for another GitHub host")

ErrInvalidRepository reports a --repo value that names no repository. It does not repeat the value, which may be a URL carrying credentials.

View Source
var ErrNotFound = errors.New("not found on GitHub")

ErrNotFound reports a repository or pull request GitHub does not show to this token.

View Source
var ErrNotGitHubRemote = errors.New("the remote does not name a repository on a GitHub host; pass --repo")

ErrNotGitHubRemote reports a remote URL that names no repository on a GitHub host. It does not repeat the URL, which may carry credentials.

View Source
var ErrUnknownHost = errors.New("not a GitHub host gh knows: use github.com, a *.ghe.com tenant, a host you ran `gh auth login` for, or GH_HOST")

ErrUnknownHost reports a host gh does not treat as GitHub. No token is looked up for it and no request is sent to it.

Functions

func IsGitHubHost

func IsGitHubHost(host string) bool

IsGitHubHost reports whether baum will talk to host: see gitHubHost.

func RemoteNames

func RemoteNames(remote string, repo Repository) bool

RemoteNames reports whether the git remote URL names repo, host included: a clone of github.com/o/n is not one of ghe.example.com/o/n. The remote is read as pull request resolution reads it (ssh.github.com is github.com, an SSH alias is resolved through `ssh -G`); a host that is not one gh treats as GitHub falls back to the URL's own host, or to an alias without a dot, whose owner/name must match.

Types

type Client

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

Client reads GitHub GraphQL evidence and read-only REST discovery metadata from any recognized GitHub host with that host's token.

func New

func New(tokens TokenSource, opts Options) *Client

New returns a client that reads each host with the token tokens returns for it.

func NewFromConfig

func NewFromConfig(cfg config.Config, opts Options) *Client

NewFromConfig returns a client whose tokens cfg resolves per host (see config.Config.ResolveGitHubToken).

func (*Client) Fetch

func (c *Client) Fetch(ctx context.Context, repo Repository, number int, opts FetchOptions) (Evidence, error)

Fetch reads pull request number of repo: its header, commits, checks and statuses at the head with whether each is required, and its comments, reviews and review threads. A part GitHub refuses is left empty, recorded false in Sources and explained in Unavailable; a missing pull request, a rate limit the client does not wait out and cancellation fail the fetch. When the head moves while the parts are read, the fetch starts over, so every part describes the same head.

func (*Client) REST

func (c *Client) REST(ctx context.Context, repository Repository) (*RESTReader, error)

func (*Client) ResolvePR

func (c *Client) ResolvePR(ctx context.Context, clone Clone, opts ResolveOptions) (Target, error)

ResolvePR finds the pull request to work on. With --pr it is that pull request on --repo or on the repository the clone's origin remote names, and no request is made. Otherwise it follows the current branch:

  • When the branch's upstream is refs/pull/N/head (or /merge) of a GitHub remote, it is pull request N there.
  • When the upstream is a branch of a GitHub remote, it is the pull request whose head is that branch, as GitHub's associatedPullRequests lists it: the open one, or else the most recently updated. That pull request may target another repository, such as the upstream of a fork.
  • Failing those, it is the pull request whose head is the branch of the same name on --repo or origin.

With --repo, a pull request found through the upstream counts only when it is in that repository. Remote URLs are read with insteadOf applied.

type Clone

type Clone interface {
	// RemoteFetchURL is the URL git fetches the named remote from, with
	// insteadOf rewrites applied; "" when there is no such remote.
	RemoteFetchURL(ctx context.Context, remote string) (string, error)
	// CurrentBranch is the branch HEAD is on, "" when detached.
	CurrentBranch(ctx context.Context) (string, error)
	// BranchUpstream is the branch's branch.<name>.remote and
	// branch.<name>.merge, each "" when unset.
	BranchUpstream(ctx context.Context, branch string) (remote, merge string, err error)
}

Clone is the local clone a pull request is resolved from; *gitlocal.Repo implements it.

type Evidence

type Evidence struct {
	// Host is the GitHub host the evidence was read from.
	Host string
	// Repository is "owner/name" as GitHub spells it.
	Repository   string
	PullRequest  bundle.PullRequest
	Checks       []bundle.Check
	Conversation []bundle.ConversationItem
	Threads      []bundle.Thread
	// Images are the images GitHub rendered from the description, for the
	// attachment step to download. Their FetchURL is signed: it is never
	// stored or logged.
	Images  []bundle.RenderedImage
	Sources bundle.Sources
	// Unavailable says why each part recorded false in Sources could not be
	// read.
	Unavailable map[string]error
}

Evidence is the GitHub-sourced part of a generation bundle for one pull request at its current head.

func (Evidence) Apply

func (e Evidence) Apply(b *bundle.Bundle)

Apply copies the evidence into b, merging its sources into b's.

type FetchOptions

type FetchOptions struct {
	// MetadataOnly reads the PR header and current checks without fetching
	// conversations, review threads, commit lists or protection rules.
	MetadataOnly bool

	// ChecksHead reads checks for this reviewed commit, while PR metadata stays current.
	// Empty uses the current pull request head.
	ChecksHead string

	// BotReportMarkers are the bot-report markers of the base branch's
	// REVIEW.md marker registry. The registry is not built yet, so callers
	// pass none.
	BotReportMarkers []string
}

FetchOptions adjust what Fetch flags.

type Options

type Options struct {
	// Transport carries the requests; nil uses http.DefaultTransport.
	Transport http.RoundTripper
}

Options configure a Client. The zero value talks to GitHub.

type RESTReader

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

RESTReader reads only relative API paths on one validated GitHub host. Its identity partitions private caches without persisting a credential.

func (*RESTReader) CacheIdentity

func (r *RESTReader) CacheIdentity() string

func (*RESTReader) Read

func (r *RESTReader) Read(ctx context.Context, path, etag string) (int, http.Header, []byte, error)

Read returns bounded raw JSON and headers, including rate and conditional response headers. Only GET is available; redirects are refused.

type RateLimitedError

type RateLimitedError struct {
	ResumeAt time.Time
	Err      error
}

RateLimitedError reports a GitHub rate limit the client did not wait out: its reset was further away than the client waits, or it persisted through every retry. ResumeAt is when GitHub said to try again, zero when unknown.

func (*RateLimitedError) Error

func (e *RateLimitedError) Error() string

func (*RateLimitedError) Unwrap

func (e *RateLimitedError) Unwrap() error

type Repository

type Repository struct {
	Host, Owner, Name string
}

Repository names a repository on a GitHub host.

func ParseRepository

func ParseRepository(value string) (Repository, error)

ParseRepository reads --repo: "owner/name" on github.com, or "host/owner/name" on another GitHub host such as an Enterprise Server, as gh reads it. The host must be one gh treats as GitHub (see gitHubHost), so a mistyped or hostile host is refused before any token is looked up.

func RepositoryFromRemote

func RepositoryFromRemote(remote string) (Repository, error)

RepositoryFromRemote reads the repository a git remote URL names, in the https, ssh and scp-like forms, as gh reads it: an SSH host alias is resolved through `ssh -G`, and ssh.github.com is github.com. The host must be one gh treats as GitHub: github.com, a *.ghe.com tenant, a host gh is logged in to, or the one GH_HOST names. Any other host is another service, which must never be sent a GitHub token.

func (Repository) String

func (r Repository) String() string

String is "owner/name" on github.com and "host/owner/name" elsewhere.

type ResolveOptions

type ResolveOptions struct {
	Repo string
	PR   int
}

ResolveOptions are the --repo and --pr flags; the zero value of each means it was not given.

type Target

type Target struct {
	Repository Repository
	Number     int
}

Target is the pull request a command works on.

type TokenSource

type TokenSource func(ctx context.Context, host string) (string, error)

TokenSource returns the token for one GitHub host. The client asks it only for the host of the repository it is about to read, and sends the token only there.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL