github

Documentation

Overview

client.go implements the GitHub REST API client for issues, pull requests, labels, and webhooks.

Index

• type Client
• type HTTPClient
  • func NewHTTPClient() *HTTPClient
  • func (c *HTTPClient) AddIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error
  • func (c *HTTPClient) CreateInstallationToken(ctx context.Context, jwt string, installationID string) (InstallationToken, error)
  • func (c *HTTPClient) CreateIssue(ctx context.Context, token, owner, repo, title, body string, labels []string) (int, error)
  • func (c *HTTPClient) CreateIssueComment(ctx context.Context, token, owner, repo string, number int, body string) (string, error)
  • func (c *HTTPClient) ExchangeOAuthCode(ctx context.Context, clientID, clientSecret, code, redirectURI string) (OAuthToken, error)
  • func (c *HTTPClient) GetAuthenticatedUser(ctx context.Context, token string) (User, error)
  • func (c *HTTPClient) GetFileContents(ctx context.Context, token, owner, repo, path, ref string) ([]byte, bool, error)
  • func (c *HTTPClient) GetIssue(ctx context.Context, token, owner, repo string, number int) (Issue, error)
  • func (c *HTTPClient) GetIssueComments(ctx context.Context, token, owner, repo string, number int) ([]IssueComment, error)
  • func (c *HTTPClient) GetIssueCommentsSince(ctx context.Context, token, owner, repo string, number int, since time.Time) ([]IssueComment, error)
  • func (c *HTTPClient) GetIssueEvents(ctx context.Context, token, owner, repo string, number int) ([]map[string]any, error)
  • func (c *HTTPClient) GetRepository(ctx context.Context, token, owner, repo string) (Repository, error)
  • func (c *HTTPClient) ListInstallationRepositories(ctx context.Context, token string, perPage, page int) (InstallationRepositoriesResponse, error)
  • func (c *HTTPClient) ListIssues(ctx context.Context, token, owner, repo string, state string, ...) ([]Issue, error)
  • func (c *HTTPClient) RemoveIssueLabel(ctx context.Context, token, owner, repo string, number int, label string) error
  • func (c *HTTPClient) ReplaceIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error
  • func (c *HTTPClient) UpdateIssueBody(ctx context.Context, token, owner, repo string, number int, body string) error
  • func (c *HTTPClient) ValidateWebhookSignature(payload []byte, signatureHeader, secret string) bool
• type InstallationRepositoriesResponse
• type InstallationToken
• type Issue
• type IssueComment
• type Label
• type OAuthToken
• type Repository
• type RequestError
  • func (e RequestError) Error() string
• type User

Types

type Client

type Client interface {
	// Issues
	CreateIssue(ctx context.Context, token, owner, repo, title, body string, labels []string) (int, error)
	CreateIssueComment(ctx context.Context, token, owner, repo string, number int, body string) (string, error)
	UpdateIssueBody(ctx context.Context, token, owner, repo string, number int, body string) error
	ReplaceIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error
	AddIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error
	RemoveIssueLabel(ctx context.Context, token, owner, repo string, number int, label string) error
	ListIssues(ctx context.Context, token, owner, repo string, state string, perPage, page int) ([]Issue, error)
	GetIssue(ctx context.Context, token, owner, repo string, number int) (Issue, error)
	GetIssueComments(ctx context.Context, token, owner, repo string, number int) ([]IssueComment, error)
	GetIssueCommentsSince(ctx context.Context, token, owner, repo string, number int, since time.Time) ([]IssueComment, error)

	// Issue Events
	GetIssueEvents(ctx context.Context, token, owner, repo string, number int) ([]map[string]any, error)

	// Repositories
	GetRepository(ctx context.Context, token, owner, repo string) (Repository, error)
	ListInstallationRepositories(ctx context.Context, token string, perPage, page int) (InstallationRepositoriesResponse, error)
	GetFileContents(ctx context.Context, token, owner, repo, path, ref string) ([]byte, bool, error)

	// OAuth
	ExchangeOAuthCode(ctx context.Context, clientID, clientSecret, code, redirectURI string) (OAuthToken, error)
	GetAuthenticatedUser(ctx context.Context, token string) (User, error)

	// App
	CreateInstallationToken(ctx context.Context, jwt string, installationID string) (InstallationToken, error)

	// Webhook
	ValidateWebhookSignature(payload []byte, signatureHeader, secret string) bool
}

Client abstracts all GitHub API interactions.

type HTTPClient

type HTTPClient struct {
	HTTP       *http.Client
	APIURL     string
	OAuthURL   string
	APIVersion string
	UserAgent  string
}

HTTPClient is the production implementation of Client using HTTP.

func NewHTTPClient

func NewHTTPClient() *HTTPClient

NewHTTPClient creates a new GitHub HTTP client with sensible defaults.

func (*HTTPClient) AddIssueLabels

func (c *HTTPClient) AddIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error

AddIssueLabels appends labels to a GitHub issue without removing existing ones.

func (*HTTPClient) CreateInstallationToken

func (c *HTTPClient) CreateInstallationToken(ctx context.Context, jwt string, installationID string) (InstallationToken, error)

CreateInstallationToken creates an installation access token using the given JWT.

func (*HTTPClient) CreateIssue

func (c *HTTPClient) CreateIssue(ctx context.Context, token, owner, repo, title, body string, labels []string) (int, error)

CreateIssue opens a new issue on a GitHub repository and returns the issue number.

func (*HTTPClient) CreateIssueComment

func (c *HTTPClient) CreateIssueComment(ctx context.Context, token, owner, repo string, number int, body string) (string, error)

CreateIssueComment posts a new comment on a GitHub issue and returns the comment URL.

func (*HTTPClient) ExchangeOAuthCode

func (c *HTTPClient) ExchangeOAuthCode(ctx context.Context, clientID, clientSecret, code, redirectURI string) (OAuthToken, error)

ExchangeOAuthCode exchanges an OAuth authorization code for an access token.

func (*HTTPClient) GetAuthenticatedUser

func (c *HTTPClient) GetAuthenticatedUser(ctx context.Context, token string) (User, error)

GetAuthenticatedUser returns the GitHub user associated with the given token.

func (*HTTPClient) GetFileContents

func (c *HTTPClient) GetFileContents(ctx context.Context, token, owner, repo, path, ref string) ([]byte, bool, error)

GetFileContents fetches the raw contents of a file from a GitHub repository. Returns (contents, found, error). If the file does not exist, returns (nil, false, nil).

func (*HTTPClient) GetIssue

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

GetIssue fetches a single GitHub issue by number.

func (*HTTPClient) GetIssueComments

func (c *HTTPClient) GetIssueComments(ctx context.Context, token, owner, repo string, number int) ([]IssueComment, error)

GetIssueComments retrieves all comments on a GitHub issue.

func (*HTTPClient) GetIssueCommentsSince

func (c *HTTPClient) GetIssueCommentsSince(ctx context.Context, token, owner, repo string, number int, since time.Time) ([]IssueComment, error)

GetIssueCommentsSince retrieves comments on a GitHub issue created or updated after the given timestamp.

func (*HTTPClient) GetIssueEvents

func (c *HTTPClient) GetIssueEvents(ctx context.Context, token, owner, repo string, number int) ([]map[string]any, error)

GetIssueEvents retrieves the timeline events for a GitHub issue.

func (*HTTPClient) GetRepository

func (c *HTTPClient) GetRepository(ctx context.Context, token, owner, repo string) (Repository, error)

GetRepository fetches metadata for a GitHub repository.

func (*HTTPClient) ListInstallationRepositories

func (c *HTTPClient) ListInstallationRepositories(ctx context.Context, token string, perPage, page int) (InstallationRepositoriesResponse, error)

ListInstallationRepositories returns a paginated list of repositories accessible to the installation.

func (*HTTPClient) ListIssues

func (c *HTTPClient) ListIssues(ctx context.Context, token, owner, repo string, state string, perPage, page int) ([]Issue, error)

ListIssues returns a paginated list of issues for a repository filtered by state.

func (*HTTPClient) RemoveIssueLabel

func (c *HTTPClient) RemoveIssueLabel(ctx context.Context, token, owner, repo string, number int, label string) error

RemoveIssueLabel removes a single label from a GitHub issue.

func (*HTTPClient) ReplaceIssueLabels

func (c *HTTPClient) ReplaceIssueLabels(ctx context.Context, token, owner, repo string, number int, labels []string) error

ReplaceIssueLabels sets the labels on a GitHub issue, replacing all existing labels.

func (*HTTPClient) UpdateIssueBody

func (c *HTTPClient) UpdateIssueBody(ctx context.Context, token, owner, repo string, number int, body string) error

UpdateIssueBody replaces the body text of a GitHub issue.

func (*HTTPClient) ValidateWebhookSignature

func (c *HTTPClient) ValidateWebhookSignature(payload []byte, signatureHeader, secret string) bool

ValidateWebhookSignature verifies a GitHub webhook payload against its HMAC-SHA256 signature.

type InstallationRepositoriesResponse

type InstallationRepositoriesResponse struct {
	TotalCount   int          `json:"total_count"`
	Repositories []Repository `json:"repositories"`
}

InstallationRepositoriesResponse is the response from listing installation repos.

type InstallationToken

type InstallationToken struct {
	Token     string `json:"token"`
	ExpiresAt string `json:"expires_at"`
}

InstallationToken represents an installation access token.

type Issue

type Issue struct {
	Number    int     `json:"number"`
	Title     string  `json:"title"`
	Body      string  `json:"body"`
	State     string  `json:"state"`
	HTMLURL   string  `json:"html_url"`
	Labels    []Label `json:"labels"`
	User      User    `json:"user"`
	CreatedAt string  `json:"created_at"`
	UpdatedAt string  `json:"updated_at"`
}

Issue represents a GitHub issue.

type IssueComment

type IssueComment struct {
	ID        int    `json:"id"`
	Body      string `json:"body"`
	HTMLURL   string `json:"html_url"`
	User      User   `json:"user"`
	CreatedAt string `json:"created_at"`
}

IssueComment represents a GitHub issue comment.

type Label

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

Label represents a GitHub label.

type OAuthToken

type OAuthToken struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	Scope       string `json:"scope"`
}

OAuthToken represents an OAuth access token response.

type Repository

type Repository struct {
	ID            int64           `json:"id"`
	FullName      string          `json:"full_name"`
	Name          string          `json:"name"`
	DefaultBranch string          `json:"default_branch"`
	Private       bool            `json:"private"`
	HTMLURL       string          `json:"html_url"`
	Permissions   map[string]bool `json:"permissions,omitempty"`
}

Repository represents a GitHub repository.

type RequestError

type RequestError struct {
	Operation  string
	StatusCode int
	Message    string
}

RequestError represents a GitHub API error.

func (RequestError) Error

func (e RequestError) Error() string

type User

type User struct {
	ID        int64  `json:"id"`
	Login     string `json:"login"`
	Name      string `json:"name,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
}

User represents a GitHub user.