gh

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package gh is a small GitHub REST client built on the user's existing GitHub CLI authentication.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsGone added in v0.3.0 

func IsGone(err error) bool

IsGone reports whether err means the resource was deleted.

func IsNotFound 

func IsNotFound(err error) bool

func IsOffline 

func IsOffline(err error) bool

IsOffline reports whether err means GitHub could not be reached, so the request is worth retrying later unchanged.

func IsValidation 

func IsValidation(err error) bool

func NormalizeRepo 

func NormalizeRepo(repo string) (string, error)

NormalizeRepo trims whitespace and a leading github.com URL from repo and validates the result.

func RepoName 

func RepoName(repo string) string

RepoName returns the name part of an owner/name reference.

func UserMessage 

func UserMessage(err error) string

UserMessage turns err into a short sentence suitable for a status bar.

func ValidRepo 

func ValidRepo(repo string) bool

ValidRepo reports whether repo is a GitHub repository in owner/name form.

Types

type Client 

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

Client talks to the GitHub REST API.

func New 

func New() (*Client, error)

New returns a client authenticated with the token `gh` uses (or GITHUB_TOKEN / GH_TOKEN). It fails with an ErrAuth error when no token is available.

func NewWithHTTP 

func NewWithHTTP(hc *http.Client, base, host string) *Client

NewWithHTTP returns a client that sends requests with hc to base, which must end with a slash. Tests use it to point the client at a fake server.

func (*Client) AddAssignees 

func (c *Client) AddAssignees(ctx context.Context, repo string, number int, logins []string) error

AddAssignees assigns users to an issue.

func (*Client) AddLabels 

func (c *Client) AddLabels(ctx context.Context, repo string, number int, labels []string) error

AddLabels adds labels to an issue. GitHub creates labels that don't exist yet.

func (*Client) CreateComment 

func (c *Client) CreateComment(ctx context.Context, repo string, number int, body string) (Comment, error)

CreateComment adds a comment to an issue.

func (*Client) CreateIssue 

func (c *Client) CreateIssue(ctx context.Context, repo string, payload NewIssue) (Issue, error)

CreateIssue opens a new issue.

func (*Client) CreateLabel 

func (c *Client) CreateLabel(ctx context.Context, repo string, label Label) error

CreateLabel defines a label in repo. A label that already exists is left unchanged and is not an error.

func (*Client) GetIssue 

func (c *Client) GetIssue(ctx context.Context, repo string, number int) (Issue, error)

GetIssue returns a single issue.

func (*Client) Host 

func (c *Client) Host() string

Host returns the GitHub host the client is authenticated against.

func (*Client) IssueURL 

func (c *Client) IssueURL(repo string, number int) string

IssueURL returns the web URL of an issue.

func (*Client) LatestRelease added in v0.3.0 

func (c *Client) LatestRelease(ctx context.Context, repo string) (Release, error)

LatestRelease returns the release GitHub marks as latest in repo.

func (*Client) ListComments 

func (c *Client) ListComments(ctx context.Context, repo string, number int) ([]Comment, error)

ListComments returns all comments on an issue, oldest first.

func (*Client) ListIssues 

func (c *Client) ListIssues(ctx context.Context, repo string, since time.Time, etag string) (IssuePage, error)

ListIssues returns every issue (not pull request) in repo updated at or after since. When etag matches GitHub's current listing, NotModified is set and no issues are returned; such requests don't count against the rate limit.

func (*Client) ListLabels 

func (c *Client) ListLabels(ctx context.Context, repo string) ([]Label, error)

ListLabels returns every label defined in repo.

func (*Client) ListUserRepos 

func (c *Client) ListUserRepos(ctx context.Context, limit int) ([]RepoSummary, error)

ListUserRepos returns repositories the user owns, collaborates on, or can access through an organization, most recently pushed first. Archived repositories and repositories with issues disabled are skipped.

func (*Client) RemoveAssignees 

func (c *Client) RemoveAssignees(ctx context.Context, repo string, number int, logins []string) error

RemoveAssignees unassigns users from an issue.

func (*Client) RemoveLabel 

func (c *Client) RemoveLabel(ctx context.Context, repo string, number int, label string) error

RemoveLabel removes a label from an issue. Removing a label the issue doesn't have is not an error.

func (*Client) UpdateIssue 

func (c *Client) UpdateIssue(ctx context.Context, repo string, number int, patch IssuePatch) (Issue, error)

UpdateIssue edits an issue's title, body, or state.

func (*Client) Viewer 

func (c *Client) Viewer(ctx context.Context) (string, error)

Viewer returns the login of the authenticated user.

type Comment 

type Comment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	User      User      `json:"user"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	HTMLURL   string    `json:"html_url"`
}

Comment is an issue comment.

type Error 

type Error struct {
	Kind    ErrorKind
	Status  int
	Message string
	Repo    string
}

Error is a classified GitHub API failure.

func (*Error) Error 

func (e *Error) Error() string

type ErrorKind 

type ErrorKind int

ErrorKind groups GitHub failures by what the user can do about them. 

const (
	ErrOther ErrorKind = iota
	ErrAuth
	ErrNotFound
	ErrPermission
	ErrValidation
	ErrRateLimited
	ErrOffline
	// ErrGone means the resource was deleted for good, e.g. a deleted issue.
	ErrGone
)

type Issue 

type Issue struct {
	Number      int        `json:"number"`
	Title       string     `json:"title"`
	Body        string     `json:"body"`
	State       string     `json:"state"`
	StateReason string     `json:"state_reason"`
	Labels      []Label    `json:"labels"`
	Assignees   []User     `json:"assignees"`
	User        User       `json:"user"`
	Comments    int        `json:"comments"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	ClosedAt    *time.Time `json:"closed_at"`
	HTMLURL     string     `json:"html_url"`
	PullRequest *struct{}  `json:"pull_request,omitempty"`
}

Issue is a GitHub issue as returned by the REST API.

type IssuePage 

type IssuePage struct {
	Issues      []Issue
	ETag        string
	NotModified bool
}

IssuePage is the result of an incremental issue listing.

type IssuePatch 

type IssuePatch struct {
	Title       *string `json:"title,omitempty"`
	Body        *string `json:"body,omitempty"`
	State       *string `json:"state,omitempty"`
	StateReason *string `json:"state_reason,omitempty"`
}

IssuePatch is the payload for UpdateIssue; nil fields are left unchanged.

type Label 

type Label struct {
	Name        string `json:"name"`
	Color       string `json:"color,omitempty"`
	Description string `json:"description,omitempty"`
}

Label is a GitHub issue label.

type NewIssue 

type NewIssue struct {
	Title     string   `json:"title"`
	Body      string   `json:"body,omitempty"`
	Labels    []string `json:"labels,omitempty"`
	Assignees []string `json:"assignees,omitempty"`
}

NewIssue is the payload for CreateIssue.

type Release added in v0.3.0 

type Release struct {
	TagName string `json:"tag_name"`
	Name    string `json:"name"`
	Body    string `json:"body"`
	HTMLURL string `json:"html_url"`
}

Release is a published GitHub release.

type RepoSummary 

type RepoSummary struct {
	FullName    string    `json:"full_name"`
	Description string    `json:"description"`
	Private     bool      `json:"private"`
	Archived    bool      `json:"archived"`
	HasIssues   bool      `json:"has_issues"`
	OpenIssues  int       `json:"open_issues_count"`
	PushedAt    time.Time `json:"pushed_at"`
}

RepoSummary describes a repository the user can access.

type User 

type User struct {
	Login string `json:"login"`
}

User is a GitHub account reference.

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.