github

Documentation

Overview

Package github implements the GitHub APIs used by Cogito (Commit status API).

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

Index

• Constants
• func ApiRoot(h string) string
• func Backoff(first bool, previous, limit time.Duration, err error) time.Duration
• func Classifier(err error) retry.Action
• func NewGitHubError(httpResp *http.Response, innerErr error) error
• func RateLimited(err GitHubError) bool
• func TransientError(statusCode int) bool
• type AddRequest
• type CommitStatus
  • func NewCommitStatus(target *Target, token, owner, repo, context string, log *slog.Logger) CommitStatus
  • func (cs CommitStatus) Add(sha, state, targetURL, description string) error
• type GitHubError
  • func (ghe GitHubError) Error() string
  • func (ghe GitHubError) Unwrap() error
• type GitURL
  • func ParseGitPseudoURL(rawURL string) (GitURL, error)
• type StatusError
  • func (e *StatusError) Error() string
• type Target

Constants

const GhDefaultHostname = "github.com"

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

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 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(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 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:

• ssh: git@github.com:Pix4D/cogito.git; will be rewritten to the valid URL ssh://git@github.com/Pix4D/cogito.git
• https: https://github.com/Pix4D/cogito.git
• https with u:p: https//username:password@github.com/Pix4D/cogito.git
• http: http://github.com/Pix4D/cogito.git
• http with u:p: http://username:password@github.com/Pix4D/cogito.git

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 {
	// Server is the GitHub API server.
	Server string
	// Retry controls the retry logic.
	Retry retry.Retry
}