github

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 20, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package github is a minimal implementation of some GitHub APIs; it integrates with the [go-kit.retry] package.

See the README and CONTRIBUTING files for additional information, caveats about GitHub API and imposed limits, and reference to official documentation.

Index

Constants

View Source 
const GhDefaultHostname = "github.com"

GhDefaultHostname is the default GitHub hostname (used for git but not for the API)

Variables

This section is empty.

Functions

func ApiRoot 

func ApiRoot(h string) string

ApiRoot constructs the root part of the GitHub API URL for a given hostname. Example: if hostname is github.com it returns https://api.github.com if hostname looks like a httptest server, it returns http://127.0.0.1:PORT otherwise, hostname is assumed to be of a Github Enterprise instance. For example, github.mycompany.org returns https://github.mycompany.org/api/v3

func Backoff 

func Backoff(first bool, previous, limit time.Duration, err error) time.Duration

Backoff implements retry.BackoffFunc for GitHub.

func Classifier 

func Classifier(err error) retry.Action

Classifier implements retry.ClassifierFunc for GitHub.

func GenerateInstallationToken 

func GenerateInstallationToken(ctx context.Context, client *http.Client, server string, app GitHubApp) (string, error)

GenerateInstallationToken returns an installation token used to authenticate as GitHub App installation

func NewGitHubError 

func NewGitHubError(httpResp *http.Response, innerErr error) error

func RateLimited 

func RateLimited(err GitHubError) bool

RateLimited returns true if the http.Response in err reports being rate limited. See https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#exceeding-the-rate-limit

func TransientError 

func TransientError(statusCode int) bool

TransientError returns true if the http.Response in err has a status code that can be retried.

Types

type AddRequest 

type AddRequest struct {
	State       string `json:"state"`
	TargetURL   string `json:"target_url"`
	Description string `json:"description"`
	Context     string `json:"context"`
}

AddRequest is the JSON object sent to the API.

type CommitStatus 

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

CommitStatus is a wrapper to the GitHub API to set the commit status for a specific GitHub owner and repo. See also: - NewCommitStatus - https://docs.github.com/en/rest/commits/statuses

func NewCommitStatus 

func NewCommitStatus(
	target *Target,
	token, owner, repo, context string,
	log *slog.Logger,
) CommitStatus

NewCommitStatus returns a CommitStatus object associated to a specific GitHub owner and repo. Parameter token is the personal OAuth token of a user that has write access to the repo. It only needs the repo:status scope. Parameter context is what created the status, for example "JOBNAME", or "PIPELINENAME/JOBNAME". The name comes from the GitHub API. Be careful when using PIPELINENAME: if that name is ephemeral, it will make it impossible to use GitHub repository branch protection rules.

See also: - https://docs.github.com/en/rest/commits/statuses

func (CommitStatus) Add 

func (cs CommitStatus) Add(ctx context.Context, sha, state, targetURL, description string) error

Add sets the commit state to the given sha, decorating it with targetURL and optional description. In case of transient errors or rate limiting by the backend, Add performs a certain number of attempts before giving up. The retry logic is configured in the Target.Retry parameter of NewCommitStatus. Parameter sha is the 40 hexadecimal digit sha associated to the commit to decorate. Parameter state is one of error, failure, pending, success. Parameter targetURL (optional) points to the specific process (for example, a CI build) that generated this state. Parameter description (optional) gives more information about the status. The returned error contains some diagnostic information to help troubleshooting.

See also: https://docs.github.com/en/rest/commits/statuses#create-a-commit-status

type GitHubApp 

type GitHubApp struct {
	ClientId       string `json:"client_id"`
	InstallationId int    `json:"installation_id"`
	PrivateKey     string `json:"private_key"` // SENSITIVE
}

func (*GitHubApp) IsZero 

func (app *GitHubApp) IsZero() bool

type GitHubError 

type GitHubError struct {
	StatusCode         int
	OauthInfo          string
	Date               time.Time
	RateLimitRemaining int
	RateLimitReset     time.Time
	// contains filtered or unexported fields
}

func (GitHubError) Error 

func (ghe GitHubError) Error() string

func (GitHubError) Unwrap 

func (ghe GitHubError) Unwrap() error

type GitURL 

type GitURL struct {
	URL      *url.URL
	Owner    string
	Repo     string
	FullName string
}

func ParseGitPseudoURL 

func ParseGitPseudoURL(rawURL string) (GitURL, error)

ParseGitPseudoURL attempts to parse rawURL as a git remote URL compatible with the Github naming conventions.

It supports the following types of git pseudo URLs:

type StatusError 

type StatusError struct {
	What       string
	StatusCode int
	Details    string
}

StatusError is one of the possible errors returned by the github package.

func (*StatusError) Error 

func (e *StatusError) Error() string

type Target 

type Target struct {
	// Client is the http client
	Client *http.Client
	// Server is the GitHub API server.
	Server string
	// Retry controls the retry logic.
	Retry retry.Retry
}

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.