Documentation
¶
Overview ¶
Package github adapts read-only GitHub APIs to product-owned values.
It contains credential resolution, typed error classification, per-attempt rate limiting, bounded retries, pagination metadata, and mapping from go-github types. Callers depend on the narrow Reader capabilities instead of importing SDK types into the application or domain layers.
Index ¶
- Constants
- Variables
- func IsNoToken(err error) bool
- type AccessDeniedError
- type Actor
- type AuthoredPullRequestSearchOptions
- type AuthoredPullRequestSearchResult
- type AuthoredPullRequestSearcher
- type Branch
- type BranchReader
- type CICheck
- type CIFailureOptions
- type CIJob
- type CIJobLog
- type CIRun
- type CircuitState
- type Client
- func (c *Client) CompareCommits(ctx context.Context, owner, repo, base, head string) (CommitComparison, RateInfo, error)
- func (c *Client) GetAuthenticatedIdentity(ctx context.Context) (Identity, RateInfo, error)
- func (c *Client) GetBranch(ctx context.Context, owner, repo, branch string) (Branch, RateInfo, error)
- func (c *Client) GetIssue(ctx context.Context, owner, name string, number int) (Issue, RateInfo, error)
- func (c *Client) GetPullRequestCI(ctx context.Context, owner, repo string, number int, opts CIFailureOptions, ...) (PullRequestCI, error)
- func (c *Client) GetPullRequestDetails(ctx context.Context, owner, name string, number int) (PullRequestDetails, RateInfo, error)
- func (c *Client) GetPullRequestFeedback(ctx context.Context, owner, repo string, number int, ...) (PullRequestFeedback, error)
- func (c *Client) GetPullRequestStatus(ctx context.Context, owner, name string, number int, ...) (PullRequestStatus, error)
- func (c *Client) GetRepository(ctx context.Context, owner, name string) (Repository, RateInfo, error)
- func (c *Client) GetRepositoryFile(ctx context.Context, owner, name, path string) (RepositoryFile, RateInfo, error)
- func (c *Client) GetRepositoryFileAtRef(ctx context.Context, owner, name, path, requestedRef string) (RepositoryFile, RateInfo, error)
- func (c *Client) GetRepositoryFileAtResolvedRef(ctx context.Context, owner, name, path string, resolution RefResolution) (RepositoryFile, RateInfo, error)
- func (c *Client) GetUser(ctx context.Context, login string) (Actor, RateInfo, error)
- func (c *Client) GetUserContributions(ctx context.Context, login string, opts UserContributionOptions) (UserContributionCollection, error)
- func (c *Client) GetUserPinnedItems(ctx context.Context, login string, limit int) (PinnedItemsResult, error)
- func (c *Client) ListIssueComments(ctx context.Context, owner, name string, issueNumber int, opts PageOptions) (ListResult[IssueComment], error)
- func (c *Client) ListIssueTimeline(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[IssueTimelineEvent], error)
- func (c *Client) ListIssues(ctx context.Context, owner, name string, opts ListIssueOptions) (ListResult[Issue], error)
- func (c *Client) ListPullRequestComments(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[ReviewComment], error)
- func (c *Client) ListPullRequestReviews(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[Review], error)
- func (c *Client) ListPullRequests(ctx context.Context, owner, name string, opts PullRequestListOptions) (ListResult[Issue], error)
- func (c *Client) ListUserOrganizations(ctx context.Context, login string, opts CursorPageOptions) (ListResult[OrganizationIdentity], error)
- func (c *Client) ListUserRepositories(ctx context.Context, login string, opts UserRepositoryOptions) (ListResult[Repository], error)
- func (c *Client) ListUserSocialAccounts(ctx context.Context, login string, opts PageOptions) (ListResult[SocialAccount], error)
- func (c *Client) ReadSourceFiles(ctx context.Context, owner, name, requestedRef string, ...) (SourceFileReadResult, error)
- func (c *Client) ResolveRepositoryRef(ctx context.Context, owner, name, requestedRef string) (RefResolution, RateInfo, error)
- func (c *Client) SearchAuthoredPullRequests(ctx context.Context, opts AuthoredPullRequestSearchOptions) (AuthoredPullRequestSearchResult, error)
- func (c *Client) SearchRepositories(ctx context.Context, opts RepositorySearchOptions) (RepositorySearchResult, error)
- func (c *Client) SearchThreads(ctx context.Context, opts ThreadSearchOptions) (ThreadSearchResult, error)
- func (c *Client) SearchUsers(ctx context.Context, opts UserSearchOptions) (UserSearchResult, error)
- type CommandRunner
- type CommitComparison
- type CommitComparisonReader
- type Config
- type ContributionDay
- type CursorPageOptions
- type FacetCoverage
- type FacetResult
- type FeedbackComment
- type FeedbackCoverage
- type FeedbackReview
- type FeedbackThread
- type GoneError
- type Identity
- type IdentityReader
- type Issue
- type IssueComment
- type IssueGetter
- type IssueTimelineEvent
- type IssueTimelineReader
- type Limiter
- type ListIssueOptions
- type ListResult
- type NotFoundError
- type OrganizationIdentity
- type PageInfo
- type PageOptions
- type PinnedItem
- type PinnedItemsResult
- type PrimaryRateLimitError
- type PullRequestCI
- type PullRequestCIReader
- type PullRequestCheck
- type PullRequestClosingIssue
- type PullRequestDetails
- type PullRequestFeedback
- type PullRequestFeedbackOptions
- type PullRequestFeedbackReader
- type PullRequestFile
- type PullRequestIndexer
- type PullRequestListOptions
- type PullRequestMergeQueueEntry
- type PullRequestMergeState
- type PullRequestReviewThread
- type PullRequestStatus
- type PullRequestStatusOptions
- type PullRequestStatusReader
- type RateInfo
- type RateLimitedTransport
- type Reader
- type RefResolution
- type Repository
- type RepositoryContributionTotal
- type RepositoryFile
- type RepositoryFileAtRefReader
- type RepositoryFileAtResolvedRefReader
- type RepositoryFileReader
- type RepositoryParent
- type RepositoryRefResolver
- type RepositorySearchOptions
- type RepositorySearchResult
- type RepositorySearcher
- type RequestBudget
- type RetryConfig
- type RetryObservation
- type Review
- type ReviewComment
- type SecondaryRateLimitError
- type SocialAccount
- type SourceFileReadItem
- type SourceFileReadOptions
- type SourceFileReadResult
- type SourceFileReader
- type SourceFileRequest
- type ThreadKind
- type ThreadSearchOptions
- type ThreadSearchResult
- type ThreadSearcher
- type TokenSource
- func ChainTokenSource(sources ...TokenSource) TokenSource
- func EnvTokenSource(name string) TokenSource
- func GhCLITokenSource(runner CommandRunner, args ...string) TokenSource
- func KeyringTokenSource(account string) TokenSource
- func NewTokenSource(explicit, envVar string, runner CommandRunner) TokenSource
- func RequireToken(source TokenSource) TokenSource
- func StaticTokenSource(token string) TokenSource
- type TransientError
- type UserContribution
- type UserContributionCollection
- type UserContributionOptions
- type UserContributionReader
- type UserOrganizationReader
- type UserPinnedItemReader
- type UserProfileReader
- type UserRepositoryOptions
- type UserRepositoryReader
- type UserSearchOptions
- type UserSearchResult
- type UserSearcher
- type UserSocialAccountReader
Constants ¶
const ( DefaultBaseURL = "https://api.github.com/" DefaultUploadURL = "https://uploads.github.com/" DefaultRequestsPerSecond = 10.0 DefaultBurst = 20 )
const DefaultEnvToken = "GITHUB_TOKEN"
DefaultEnvToken is the conventional environment variable name for a GitHub token.
const KeyringService = "gitcontribute"
KeyringService is the service name used for credentials owned by gitcontribute.
Variables ¶
var ErrCircuitOpen = errors.New("circuit breaker is open")
ErrCircuitOpen is returned when the circuit breaker rejects a request.
var ErrNoToken = errors.New("no GitHub token available")
ErrNoToken indicates that a token source could not provide a token.
var ErrRequestBudgetExhausted = errors.New("github request budget exhausted")
var ErrRequiredToken = errors.New("configured GitHub token unavailable")
ErrRequiredToken indicates that an explicitly configured authentication source did not provide a token.
Functions ¶
Types ¶
type AccessDeniedError ¶
AccessDeniedError indicates that the current GitHub credentials cannot read a resource. It covers authenticated and unauthenticated denial responses.
func (*AccessDeniedError) Error ¶
func (e *AccessDeniedError) Error() string
type Actor ¶ added in v1.0.0
type Actor struct {
Login string
ID int64
NodeID string
Kind string
AvatarURL *string
Name *string
Bio *string
Company *string
Location *string
WebsiteURL *string
PublicEmail *string
TwitterUsername *string
Hireable *bool
Followers *int
Following *int
PublicRepositories *int
PublicGists *int
CreatedAt time.Time
UpdatedAt time.Time
}
Actor is a domain-neutral GitHub account profile. Nullable fields preserve provider omission and visibility instead of manufacturing zero values.
type AuthoredPullRequestSearchOptions ¶ added in v0.5.0
type AuthoredPullRequestSearchOptions struct {
Login string
RepositoryOwner string
RepositoryName string
State string
UpdatedAfter time.Time
PageOptions
}
AuthoredPullRequestSearchOptions selects one bounded authored-PR search page. UpdatedAfter is translated to GitHub Search's UTC date-granularity qualifier.
type AuthoredPullRequestSearchResult ¶ added in v0.5.0
type AuthoredPullRequestSearchResult struct {
Total int
Incomplete bool
Items []Issue
Page PageInfo
Rate RateInfo
}
AuthoredPullRequestSearchResult preserves GitHub's pagination, rate, and incomplete-results signals alongside the converted pull-request markers.
type AuthoredPullRequestSearcher ¶ added in v0.5.0
type AuthoredPullRequestSearcher interface {
SearchAuthoredPullRequests(context.Context, AuthoredPullRequestSearchOptions) (AuthoredPullRequestSearchResult, error)
}
AuthoredPullRequestSearcher discovers pull requests authored by one login.
type BranchReader ¶ added in v1.1.0
type BranchReader interface {
GetBranch(context.Context, string, string, string) (Branch, RateInfo, error)
}
BranchReader reads one exact branch tip without mutating local state.
type CIFailureOptions ¶ added in v0.16.0
type CIRun ¶ added in v0.16.0
type CIRun struct {
ID int64 `json:"id"`
Name string `json:"name"`
Event string `json:"event"`
Status string `json:"status"`
Conclusion string `json:"conclusion"`
HTMLURL string `json:"html_url,omitempty"`
Attempt int `json:"attempt"`
Jobs []CIJob `json:"jobs"`
JobsTruncated bool `json:"jobs_truncated"`
}
type CircuitState ¶
type CircuitState int
CircuitState represents the state of the circuit breaker.
const ( CircuitClosed CircuitState = iota // normal operation, requests pass through CircuitOpen // failing fast, no requests allowed CircuitHalfOpen // probing, single request allowed )
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps go-github behind a narrow, domain-neutral interface.
func (*Client) CompareCommits ¶ added in v1.1.0
func (c *Client) CompareCommits(ctx context.Context, owner, repo, base, head string) (CommitComparison, RateInfo, error)
CompareCommits reads one bounded comparison. The provider accepts an owner-qualified head such as "fork-owner:main" when the repositories share a fork network, so callers can compare an upstream default branch with a contributor fork without fetching or writing local refs.
func (*Client) GetAuthenticatedIdentity ¶ added in v0.5.0
GetAuthenticatedIdentity resolves the user associated with the configured read credential.
func (*Client) GetBranch ¶ added in v1.1.0
func (c *Client) GetBranch(ctx context.Context, owner, repo, branch string) (Branch, RateInfo, error)
GetBranch reads one branch tip without requesting protection details or mutating local refs.
func (*Client) GetIssue ¶
func (c *Client) GetIssue(ctx context.Context, owner, name string, number int) (Issue, RateInfo, error)
GetIssue reads one issue or pull-request marker by number.
func (*Client) GetPullRequestCI ¶ added in v0.16.0
func (c *Client) GetPullRequestCI(ctx context.Context, owner, repo string, number int, opts CIFailureOptions, budget *RequestBudget) (PullRequestCI, error)
func (*Client) GetPullRequestDetails ¶
func (c *Client) GetPullRequestDetails(ctx context.Context, owner, name string, number int) (PullRequestDetails, RateInfo, error)
GetPullRequestDetails reads pull-request metadata not present on issue list rows.
func (*Client) GetPullRequestFeedback ¶ added in v0.16.0
func (c *Client) GetPullRequestFeedback(ctx context.Context, owner, repo string, number int, opts PullRequestFeedbackOptions, budget *RequestBudget) (PullRequestFeedback, error)
func (*Client) GetPullRequestStatus ¶ added in v0.6.0
func (c *Client) GetPullRequestStatus(ctx context.Context, owner, name string, number int, opts PullRequestStatusOptions) (PullRequestStatus, error)
GetPullRequestStatus reads one bounded GraphQL snapshot of the PR's health facts. Collection truncation is returned as incomplete coverage; it is never silently treated as an empty or complete facet.
func (*Client) GetRepository ¶
func (c *Client) GetRepository(ctx context.Context, owner, name string) (Repository, RateInfo, error)
GetRepository reads repository metadata and the response rate-limit state.
func (*Client) GetRepositoryFile ¶ added in v0.8.0
func (c *Client) GetRepositoryFile(ctx context.Context, owner, name, path string) (RepositoryFile, RateInfo, error)
GetRepositoryFile reads one text file at GitHub's HEAD after resolving that ref to a commit. Callers that need a named branch or tag should use GetRepositoryFileAtRef directly.
func (*Client) GetRepositoryFileAtRef ¶ added in v0.18.0
func (c *Client) GetRepositoryFileAtRef(ctx context.Context, owner, name, path, requestedRef string) (RepositoryFile, RateInfo, error)
GetRepositoryFileAtRef resolves requestedRef once and reads the file at the resulting commit. A named branch or tag is never used as authoritative provenance after this method returns.
func (*Client) GetRepositoryFileAtResolvedRef ¶ added in v0.18.0
func (c *Client) GetRepositoryFileAtResolvedRef(ctx context.Context, owner, name, path string, resolution RefResolution) (RepositoryFile, RateInfo, error)
GetRepositoryFileAtResolvedRef reads contents with the resolved commit in the ref query parameter. It performs no ref resolution or other network access beyond the content request itself.
func (*Client) GetUserContributions ¶ added in v1.0.0
func (c *Client) GetUserContributions(ctx context.Context, login string, opts UserContributionOptions) (UserContributionCollection, error)
func (*Client) GetUserPinnedItems ¶ added in v1.0.0
func (*Client) ListIssueComments ¶
func (c *Client) ListIssueComments(ctx context.Context, owner, name string, issueNumber int, opts PageOptions) (ListResult[IssueComment], error)
ListIssueComments reads one page of issue comments for a thread.
func (*Client) ListIssueTimeline ¶ added in v0.6.0
func (c *Client) ListIssueTimeline(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[IssueTimelineEvent], error)
ListIssueTimeline reads one REST timeline page without exposing go-github models beyond the adapter boundary.
func (*Client) ListIssues ¶
func (c *Client) ListIssues(ctx context.Context, owner, name string, opts ListIssueOptions) (ListResult[Issue], error)
ListIssues reads one page of issues and pull-request markers for a repository.
func (*Client) ListPullRequestComments ¶
func (c *Client) ListPullRequestComments(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[ReviewComment], error)
ListPullRequestComments reads one page of pull-request review comments.
func (*Client) ListPullRequestReviews ¶
func (c *Client) ListPullRequestReviews(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[Review], error)
ListPullRequestReviews reads one page of pull-request reviews.
func (*Client) ListPullRequests ¶ added in v0.19.0
func (c *Client) ListPullRequests(ctx context.Context, owner, name string, opts PullRequestListOptions) (ListResult[Issue], error)
ListPullRequests reads one provider page of pull requests in a repository. GitHub exposes these through the repository issue list; filtering here keeps provider pagination intact while the application receives only PR markers.
func (*Client) ListUserOrganizations ¶ added in v1.0.0
func (c *Client) ListUserOrganizations(ctx context.Context, login string, opts CursorPageOptions) (ListResult[OrganizationIdentity], error)
func (*Client) ListUserRepositories ¶ added in v1.0.0
func (c *Client) ListUserRepositories(ctx context.Context, login string, opts UserRepositoryOptions) (ListResult[Repository], error)
ListUserRepositories reads one bounded owned or affiliated repository page.
func (*Client) ListUserSocialAccounts ¶ added in v1.0.0
func (c *Client) ListUserSocialAccounts(ctx context.Context, login string, opts PageOptions) (ListResult[SocialAccount], error)
ListUserSocialAccounts reads one bounded social-account page.
func (*Client) ReadSourceFiles ¶ added in v0.18.0
func (c *Client) ReadSourceFiles(ctx context.Context, owner, name, requestedRef string, requests []SourceFileRequest, opts SourceFileReadOptions) (SourceFileReadResult, error)
ReadSourceFiles resolves one ref and reads a bounded, ordered batch. Limits apply to decoded file bytes before line-range slicing so a large remote file cannot bypass the per-file acquisition bound.
func (*Client) ResolveRepositoryRef ¶ added in v0.18.0
func (c *Client) ResolveRepositoryRef(ctx context.Context, owner, name, requestedRef string) (RefResolution, RateInfo, error)
ResolveRepositoryRef resolves one branch, tag, or commit to a commit SHA.
func (*Client) SearchAuthoredPullRequests ¶ added in v0.5.0
func (c *Client) SearchAuthoredPullRequests(ctx context.Context, opts AuthoredPullRequestSearchOptions) (AuthoredPullRequestSearchResult, error)
SearchAuthoredPullRequests searches one bounded page of PRs authored by a login and preserves GitHub's incomplete-results signal.
func (*Client) SearchRepositories ¶
func (c *Client) SearchRepositories(ctx context.Context, opts RepositorySearchOptions) (RepositorySearchResult, error)
SearchRepositories reads one page from GitHub's repository Search API.
func (*Client) SearchThreads ¶ added in v0.18.0
func (c *Client) SearchThreads(ctx context.Context, opts ThreadSearchOptions) (ThreadSearchResult, error)
SearchThreads searches one repository through GitHub's issue-search endpoint. The repository, kind, and state qualifiers are part of the preserved provider query; sort and order remain explicit request options.
func (*Client) SearchUsers ¶ added in v1.0.0
func (c *Client) SearchUsers(ctx context.Context, opts UserSearchOptions) (UserSearchResult, error)
SearchUsers reads one page from GitHub's user Search API. Search results are identity stubs and intentionally do not trigger per-result profile reads.
type CommandRunner ¶
type CommandRunner interface {
Run(ctx context.Context, name string, args ...string) (string, error)
}
CommandRunner abstracts process execution so that tests can inject behavior.
func DefaultCommandRunner ¶
func DefaultCommandRunner() CommandRunner
DefaultCommandRunner returns the real command runner.
type CommitComparison ¶ added in v1.1.0
type CommitComparison struct {
Status string
BaseSHA string
MergeBaseSHA string
AheadBy int
BehindBy int
}
CommitComparison is the bounded ancestry result for two refs in one repository network. Base and head are the requested comparison directions.
type CommitComparisonReader ¶ added in v1.1.0
type CommitComparisonReader interface {
CompareCommits(context.Context, string, string, string, string) (CommitComparison, RateInfo, error)
}
CommitComparisonReader compares refs in one GitHub repository network and preserves the provider's merge-base evidence.
type Config ¶
type Config struct {
BaseURL string
UploadURL string
TokenSource TokenSource
HTTPClient *http.Client
Limiter Limiter
RequestsPerSecond float64
Burst int
Retry *RetryConfig
}
Config controls how the GitHub client is constructed.
type ContributionDay ¶ added in v1.0.0
type CursorPageOptions ¶ added in v1.0.0
type FacetCoverage ¶ added in v0.6.0
FacetCoverage describes exactly how much of a GitHub collection was returned. Callers must not replace a complete child snapshot when Complete is false.
type FacetResult ¶ added in v0.6.0
type FacetResult[T any] struct { Items []T Coverage FacetCoverage }
FacetResult pairs product-owned GitHub values with their source coverage.
type FeedbackComment ¶ added in v0.16.0
type FeedbackComment struct {
ID int64 `json:"id"`
NodeID string `json:"node_id,omitempty"`
Author string `json:"author,omitempty"`
Body string `json:"body,omitempty"`
Path string `json:"path,omitempty"`
Line *int `json:"line,omitempty"`
StartLine *int `json:"start_line,omitempty"`
Side string `json:"side,omitempty"`
StartSide string `json:"start_side,omitempty"`
CommitOID string `json:"commit_oid,omitempty"`
InReplyToID int64 `json:"in_reply_to_id,omitempty"`
CreatedAt time.Time `json:"created_at,omitempty"`
UpdatedAt time.Time `json:"updated_at,omitempty"`
Outdated bool `json:"outdated,omitempty"`
}
type FeedbackCoverage ¶ added in v0.16.0
type FeedbackReview ¶ added in v0.16.0
type FeedbackReview struct {
ID int64 `json:"id"`
NodeID string `json:"node_id,omitempty"`
Author string `json:"author,omitempty"`
State string `json:"state,omitempty"`
Body string `json:"body,omitempty"`
CommitOID string `json:"commit_oid,omitempty"`
SubmittedAt time.Time `json:"submitted_at,omitempty"`
}
type FeedbackThread ¶ added in v0.16.0
type FeedbackThread struct {
ID string `json:"id"`
Resolved bool `json:"resolved"`
ResolvedBy string `json:"resolved_by,omitempty"`
Outdated bool `json:"outdated"`
Path string `json:"path,omitempty"`
Line *int `json:"line,omitempty"`
StartLine *int `json:"start_line,omitempty"`
Comments []FeedbackComment `json:"comments"`
Truncated bool `json:"truncated"`
TotalCount int `json:"total_count"`
}
type GoneError ¶
type GoneError struct {
Resource string
}
GoneError indicates that GitHub reports a resource as permanently removed.
type Identity ¶ added in v0.5.0
Identity is the stable login and identifiers associated with the active GitHub read credential.
type IdentityReader ¶ added in v0.5.0
type IdentityReader interface {
GetAuthenticatedIdentity(context.Context) (Identity, RateInfo, error)
}
IdentityReader resolves the authenticated GitHub account without granting any mutation capability.
type Issue ¶
type Issue struct {
RepositoryOwner string
RepositoryName string
ID int64
NodeID string
Number int
Kind ThreadKind
Title string
Body string
State string
StateReason string
Draft bool
Locked bool
Author string
AuthorAssociation string
Labels []string
Assignees []string
Milestone string
CommentsCount int
CreatedAt time.Time
UpdatedAt time.Time
ClosedAt *time.Time
HTMLURL string
PullRequestURL string
}
Issue is a domain-neutral view of an issue or pull-request marker from the issues list endpoint.
type IssueComment ¶
type IssueComment struct {
ID int64
NodeID string
Body string
Author string
AuthorAssociation string
CreatedAt time.Time
UpdatedAt time.Time
HTMLURL string
IssueURL string
}
IssueComment is a domain-neutral view of an issue comment.
type IssueGetter ¶
type IssueGetter interface {
GetIssue(ctx context.Context, owner, name string, number int) (Issue, RateInfo, error)
}
IssueGetter is the optional exact-thread capability used by bounded archive refreshes. Keeping it separate avoids forcing broad discovery readers to implement an operation they do not need.
type IssueTimelineEvent ¶ added in v0.6.0
type IssueTimelineEvent struct {
ID int64
Event string
Actor string
CommitID string
CreatedAt time.Time
SourceOwner string
SourceRepository string
SourceNumber int
SourceIsPullRequest bool
}
IssueTimelineEvent is a product-owned view of one issue timeline event. Source fields are populated only for explicit cross-reference events; callers must not infer relationships from URLs or prose.
type IssueTimelineReader ¶ added in v0.6.0
type IssueTimelineReader interface {
ListIssueTimeline(context.Context, string, string, int, PageOptions) (ListResult[IssueTimelineEvent], error)
}
IssueTimelineReader is the optional, paginated issue-history capability. It stays separate from Reader so archive-only and test readers remain narrow.
type Limiter ¶
Limiter paces outbound requests. It matches the subset of rate.Limiter used by the transport so tests can inject a no-op or fake implementation.
func NewRateLimiter ¶
NewRateLimiter returns a token-bucket limiter suitable for production use.
type ListIssueOptions ¶
type ListIssueOptions struct {
State string
Sort string
Direction string
Since time.Time
Labels []string
PageOptions
}
ListIssueOptions specifies filters and pagination for listing repository issues.
type ListResult ¶
ListResult is the common wrapper for paginated list responses.
type NotFoundError ¶
type NotFoundError struct {
Resource string
}
NotFoundError indicates a requested GitHub resource was not found.
func (*NotFoundError) Error ¶
func (e *NotFoundError) Error() string
type OrganizationIdentity ¶ added in v1.0.0
type PageInfo ¶
type PageInfo struct {
Page int
PerPage int
NextPage int
PrevPage int
FirstPage int
LastPage int
HasNext bool
HasPrev bool
HasFirst bool
HasLast bool
EndCursor string
}
PageInfo carries response pagination metadata.
type PageOptions ¶
PageOptions specifies pagination parameters.
type PinnedItem ¶ added in v1.0.0
type PinnedItemsResult ¶ added in v1.0.0
type PinnedItemsResult struct {
Items []PinnedItem
ShowcaseKind string
Coverage FacetCoverage
Rate RateInfo
}
type PrimaryRateLimitError ¶
PrimaryRateLimitError is returned when GitHub's primary rate limit has been exceeded.
func (*PrimaryRateLimitError) Error ¶
func (e *PrimaryRateLimitError) Error() string
type PullRequestCI ¶ added in v0.16.0
type PullRequestCIReader ¶ added in v0.16.0
type PullRequestCIReader interface {
GetPullRequestCI(context.Context, string, string, int, CIFailureOptions, *RequestBudget) (PullRequestCI, error)
}
type PullRequestCheck ¶ added in v0.6.0
type PullRequestCheck struct {
Kind string
Name string
Status string
Conclusion string
DetailsURL string
StartedAt *time.Time
CompletedAt *time.Time
}
PullRequestCheck is one check-run or commit status in the head commit's status-check rollup.
type PullRequestClosingIssue ¶ added in v0.6.0
type PullRequestClosingIssue struct {
NodeID string
RepositoryFullName string
Number int
HTMLURL string
}
PullRequestClosingIssue is an issue GitHub reports this PR will close.
type PullRequestDetails ¶
type PullRequestDetails struct {
ID int64
NodeID string
Number int
State string
Title string
Body string
Draft bool
Locked bool
Author string
AuthorAssociation string
Labels []string
Assignees []string
Milestone string
CreatedAt time.Time
UpdatedAt time.Time
ClosedAt *time.Time
MergedAt *time.Time
Merged bool
Mergeable *bool
MergeCommitSHA string
HeadRef string
HeadSHA string
HeadOwner string
HeadRepo string
BaseRef string
BaseSHA string
CommentsCount int
Commits int
Additions int
Deletions int
ChangedFiles int
HTMLURL string
}
PullRequestDetails is the PR-specific metadata beyond the issue marker.
type PullRequestFeedback ¶ added in v0.16.0
type PullRequestFeedback struct {
// Header is the PR response already fetched before the child feedback
// channels. It is used by the application layer to seed the local identity
// required by the persisted feedback facets and is not part of the facet
// payload itself.
Header PullRequestDetails `json:"-"`
HeadSHA string `json:"head_sha"`
SourceUpdatedAt time.Time `json:"source_updated_at"`
ThreadState string `json:"thread_state,omitempty"`
IssueComments []FeedbackComment `json:"issue_comments,omitempty"`
Reviews []FeedbackReview `json:"submitted_reviews,omitempty"`
InlineComments []FeedbackComment `json:"inline_comments,omitempty"`
ReviewThreads []FeedbackThread `json:"review_threads,omitempty"`
Coverage map[string]FeedbackCoverage `json:"coverage"`
}
type PullRequestFeedbackOptions ¶ added in v0.16.0
type PullRequestFeedbackReader ¶ added in v0.16.0
type PullRequestFeedbackReader interface {
GetPullRequestFeedback(context.Context, string, string, int, PullRequestFeedbackOptions, *RequestBudget) (PullRequestFeedback, error)
}
type PullRequestFile ¶ added in v0.6.0
PullRequestFile is a changed path in the PR snapshot.
type PullRequestIndexer ¶ added in v0.19.0
type PullRequestIndexer interface {
ListPullRequests(context.Context, string, string, PullRequestListOptions) (ListResult[Issue], error)
}
PullRequestIndexer lists every pull-request marker in one repository. It is intentionally separate from Reader so callers can require repository-wide, resumable discovery without widening unrelated GitHub adapters.
type PullRequestListOptions ¶ added in v0.19.0
type PullRequestListOptions struct {
State string
Sort string
Direction string
PageOptions
}
PullRequestListOptions selects one bounded repository-wide pull-request discovery page. State=all is required by repository feedback indexing.
type PullRequestMergeQueueEntry ¶ added in v0.6.0
type PullRequestMergeQueueEntry struct {
NodeID string
State string
Position int
EnqueuedAt time.Time
EstimatedTimeToMergeSeconds *int
}
PullRequestMergeQueueEntry describes the PR's current queue entry.
type PullRequestMergeState ¶ added in v0.6.0
PullRequestMergeState preserves GitHub's detailed merge state while making null and UNKNOWN mergeability explicitly unknown rather than negative.
type PullRequestReviewThread ¶ added in v0.6.0
type PullRequestReviewThread struct {
NodeID string
IsResolved bool
IsOutdated bool
Path string
Line *int
StartLine *int
}
PullRequestReviewThread is one source review conversation. IsResolved is retained so callers can derive unresolved-thread counts without inference.
type PullRequestStatus ¶ added in v0.6.0
type PullRequestStatus struct {
NodeID string
HeadSHA string
SourceUpdatedAt time.Time
MergeState PullRequestMergeState
MergeStateCoverage FacetCoverage
MergeQueue *PullRequestMergeQueueEntry
MergeQueueCoverage FacetCoverage
Checks FacetResult[PullRequestCheck]
ReviewThreads FacetResult[PullRequestReviewThread]
ClosingIssues FacetResult[PullRequestClosingIssue]
Files FacetResult[PullRequestFile]
}
PullRequestStatus is a bounded, source-backed health snapshot. Scalar coverage is separate from values so an observed absence (for example, not queued) is distinguishable from unavailable data.
type PullRequestStatusOptions ¶ added in v0.6.0
PullRequestStatusOptions bounds each collection returned by a single source-backed pull-request status read. GitHub currently caps these connections at 100 items per request.
type PullRequestStatusReader ¶ added in v0.6.0
type PullRequestStatusReader interface {
GetPullRequestStatus(context.Context, string, string, int, PullRequestStatusOptions) (PullRequestStatus, error)
}
PullRequestStatusReader reads bounded, source-backed PR health facets.
type RateLimitedTransport ¶
type RateLimitedTransport struct {
Base http.RoundTripper
Limiter Limiter
}
RateLimitedTransport wraps an underlying RoundTripper with request pacing. It does not log request contents or tokens.
type Reader ¶
type Reader interface {
GetRepository(ctx context.Context, owner, name string) (Repository, RateInfo, error)
ListIssues(ctx context.Context, owner, name string, opts ListIssueOptions) (ListResult[Issue], error)
ListIssueComments(ctx context.Context, owner, name string, issueNumber int, opts PageOptions) (ListResult[IssueComment], error)
GetPullRequestDetails(ctx context.Context, owner, name string, number int) (PullRequestDetails, RateInfo, error)
ListPullRequestReviews(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[Review], error)
ListPullRequestComments(ctx context.Context, owner, name string, number int, opts PageOptions) (ListResult[ReviewComment], error)
}
Reader is the product-owned read contract for GitHub.
type RefResolution ¶ added in v0.18.0
RefResolution records the provider ref supplied by a caller and the commit that GitHub resolved it to. CommitSHA is the authoritative source revision; ResolvedRef is the ref used for the content request (normally that commit).
type Repository ¶
type Repository struct {
ID int64
NodeID string
Owner string
Name string
FullName string
Description string
DefaultBranch string
HTMLURL string
Private bool
Fork bool
Parent *RepositoryParent
Archived bool
IsTemplate bool
Stars int
Watchers int
Forks int
OpenIssues int
Language string
License string
Topics []string
CreatedAt time.Time
UpdatedAt time.Time
PushedAt *time.Time
}
Repository is a domain-neutral view of a GitHub repository.
type RepositoryContributionTotal ¶ added in v1.0.0
type RepositoryFile ¶ added in v0.8.0
type RepositoryFile struct {
Path string
BlobSHA string
CommitSHA string
RequestedRef string
ResolvedRef string
HTMLURL string
Content string
}
RepositoryFile is a bounded text file read from a repository at an explicit resolved revision. Content API types terminate in the GitHub adapter.
type RepositoryFileAtRefReader ¶ added in v0.18.0
type RepositoryFileAtRefReader interface {
GetRepositoryFileAtRef(ctx context.Context, owner, name, path, requestedRef string) (RepositoryFile, RateInfo, error)
}
RepositoryFileAtRefReader reads one file at an explicit named ref. The adapter resolves the ref before requesting contents and preserves both the requested ref and resolved commit in RepositoryFile.
type RepositoryFileAtResolvedRefReader ¶ added in v0.18.0
type RepositoryFileAtResolvedRefReader interface {
GetRepositoryFileAtResolvedRef(ctx context.Context, owner, name, path string, resolution RefResolution) (RepositoryFile, RateInfo, error)
}
RepositoryFileAtResolvedRefReader reads one file using a resolution already shared by a caller, avoiding one ref-resolution request per file.
type RepositoryFileReader ¶ added in v0.8.0
type RepositoryFileReader interface {
GetRepositoryFile(ctx context.Context, owner, name, path string) (RepositoryFile, RateInfo, error)
}
RepositoryFileReader is the optional exact-file capability used to ingest a small, fixed set of contribution-policy documents during explicit syncs.
type RepositoryParent ¶ added in v1.1.0
RepositoryParent identifies the upstream repository reported for a fork. It intentionally retains only the identity needed at the application boundary rather than re-exporting the provider's nested repository model.
type RepositoryRefResolver ¶ added in v0.18.0
type RepositoryRefResolver interface {
ResolveRepositoryRef(ctx context.Context, owner, name, requestedRef string) (RefResolution, RateInfo, error)
}
RepositoryRefResolver resolves a named branch, tag, or commit to one authoritative commit. The result is a read-only provenance record.
type RepositorySearchOptions ¶
type RepositorySearchOptions struct {
Query string
Sort string
Order string
PageOptions
}
RepositorySearchOptions controls one GitHub repository search page.
type RepositorySearchResult ¶
type RepositorySearchResult struct {
Total int
Incomplete bool
Items []Repository
Page PageInfo
Rate RateInfo
}
RepositorySearchResult preserves GitHub's truncation and pagination facts.
type RepositorySearcher ¶
type RepositorySearcher interface {
SearchRepositories(ctx context.Context, opts RepositorySearchOptions) (RepositorySearchResult, error)
}
RepositorySearcher is the optional GitHub Search capability used by broad discovery. Keeping it separate lets archive-only readers stay small.
type RequestBudget ¶ added in v0.16.0
type RequestBudget struct {
// contains filtered or unexported fields
}
func NewRequestBudget ¶ added in v0.16.0
func NewRequestBudget(limit int) *RequestBudget
func (*RequestBudget) Completed ¶ added in v0.16.0
func (b *RequestBudget) Completed() int
func (*RequestBudget) Take ¶ added in v0.16.0
func (b *RequestBudget) Take() error
type RetryConfig ¶
type RetryConfig struct {
MaxAttempts int
BaseDelay time.Duration
MaxDelay time.Duration
Clock func() time.Time
Sleeper func(context.Context, time.Duration) error
Jitter func(time.Duration) time.Duration
OnAttempt func(RetryObservation)
}
RetryConfig controls how the retry transport paces and observes retries.
func DefaultRetryConfig ¶
func DefaultRetryConfig() *RetryConfig
DefaultRetryConfig returns a production retry policy.
type RetryObservation ¶
type RetryObservation struct {
Attempt int
StatusCode int
RateLimit RateInfo
Delay time.Duration
APIVersion string
SourceURL string
Context context.Context
}
RetryObservation reports the outcome and pacing of a single retry attempt.
type Review ¶
type Review struct {
ID int64
NodeID string
State string
Body string
Author string
AuthorAssociation string
CommitID string
SubmittedAt time.Time
HTMLURL string
PullRequestURL string
}
Review is a domain-neutral view of a pull request review.
type ReviewComment ¶
type ReviewComment struct {
ID int64
NodeID string
InReplyTo int64
Body string
Path string
DiffHunk string
Author string
AuthorAssociation string
CommitID string
OriginalCommitID string
PullRequestURL string
HTMLURL string
CreatedAt time.Time
UpdatedAt time.Time
Line int
OriginalLine int
StartLine int
OriginalStartLine int
Side string
StartSide string
Position int
OriginalPosition int
SubjectType string
}
ReviewComment is a domain-neutral view of a pull request review comment.
type SecondaryRateLimitError ¶
SecondaryRateLimitError is returned when GitHub's secondary (abuse) rate limit has been exceeded.
func (*SecondaryRateLimitError) Error ¶
func (e *SecondaryRateLimitError) Error() string
type SocialAccount ¶ added in v1.0.0
type SourceFileReadItem ¶ added in v0.18.0
type SourceFileReadItem struct {
Request SourceFileRequest
Status string
File RepositoryFile
StartLine int
EndLine int
Bytes int
ContentSHA string
Message string
RetryAfter time.Duration
}
SourceFileReadItem is one ordered adapter-level content outcome. Content is populated only for complete reads; callers may persist the item unchanged.
type SourceFileReadOptions ¶ added in v0.18.0
SourceFileReadOptions bounds one batch of repository content reads.
type SourceFileReadResult ¶ added in v0.18.0
type SourceFileReadResult struct {
Resolution RefResolution
Items []SourceFileReadItem
TotalBytes int
Rate RateInfo
}
SourceFileReadResult preserves the single resolved revision and rate state shared by a bounded source-file batch.
type SourceFileReader ¶ added in v0.18.0
type SourceFileReader interface {
ReadSourceFiles(ctx context.Context, owner, name, requestedRef string, requests []SourceFileRequest, opts SourceFileReadOptions) (SourceFileReadResult, error)
}
SourceFileReader is the optional bounded batch source acquisition capability.
type SourceFileRequest ¶ added in v0.18.0
SourceFileRequest identifies one repository-relative file and optional inclusive 1-based line range. A zero range requests the complete file.
type ThreadKind ¶
type ThreadKind string
ThreadKind classifies an issue-list entry.
const ( ThreadKindIssue ThreadKind = "issue" ThreadKindPullRequest ThreadKind = "pull_request" )
type ThreadSearchOptions ¶ added in v0.18.0
type ThreadSearchOptions struct {
Owner string
Repo string
Query string
Kind ThreadKind
State string
Sort string
Order string
PageOptions
}
ThreadSearchOptions selects one bounded GitHub issue-search page for one repository. Query is the user text before provider qualifiers are added.
type ThreadSearchResult ¶ added in v0.18.0
type ThreadSearchResult struct {
Query string
Total int
Incomplete bool
Items []Issue
Page PageInfo
Rate RateInfo
}
ThreadSearchResult preserves the exact provider query and search metadata.
type ThreadSearcher ¶ added in v0.18.0
type ThreadSearcher interface {
SearchThreads(ctx context.Context, opts ThreadSearchOptions) (ThreadSearchResult, error)
}
ThreadSearcher is the optional live GitHub issue-search capability.
type TokenSource ¶
TokenSource resolves a GitHub authentication token.
func ChainTokenSource ¶
func ChainTokenSource(sources ...TokenSource) TokenSource
ChainTokenSource tries each source in order and returns the first non-empty token. Sources that return ErrNoToken are skipped.
func EnvTokenSource ¶
func EnvTokenSource(name string) TokenSource
EnvTokenSource resolves a token from an environment variable.
func GhCLITokenSource ¶
func GhCLITokenSource(runner CommandRunner, args ...string) TokenSource
GhCLITokenSource resolves a token by running `gh auth token`. Optional args are passed through to `gh` (for example a `--hostname` flag).
func KeyringTokenSource ¶
func KeyringTokenSource(account string) TokenSource
KeyringTokenSource resolves a token from the operating system credential store. account identifies the credential within the gitcontribute service.
func NewTokenSource ¶
func NewTokenSource(explicit, envVar string, runner CommandRunner) TokenSource
NewTokenSource builds the standard resolution chain: explicit value, environment variable, then `gh auth token`.
func RequireToken ¶
func RequireToken(source TokenSource) TokenSource
RequireToken prevents an explicitly configured source from silently falling back to anonymous GitHub access.
func StaticTokenSource ¶
func StaticTokenSource(token string) TokenSource
StaticTokenSource returns the provided token if it is non-empty.
type TransientError ¶
type TransientError struct {
Cause error
}
TransientError wraps a potentially retryable error.
func (*TransientError) Error ¶
func (e *TransientError) Error() string
func (*TransientError) Unwrap ¶
func (e *TransientError) Unwrap() error
type UserContribution ¶ added in v1.0.0
type UserContributionCollection ¶ added in v1.0.0
type UserContributionCollection struct {
StartedAt time.Time
EndedAt time.Time
TotalCommits int
TotalIssues int
TotalPullRequests int
TotalPullRequestReviews int
TotalRepositories int
RestrictedContributions int
Days []ContributionDay
Items []UserContribution
RepositoryTotals []RepositoryContributionTotal
Complete bool
Rate RateInfo
}
type UserContributionOptions ¶ added in v1.0.0
type UserContributionReader ¶ added in v1.0.0
type UserContributionReader interface {
GetUserContributions(context.Context, string, UserContributionOptions) (UserContributionCollection, error)
}
type UserOrganizationReader ¶ added in v1.0.0
type UserOrganizationReader interface {
ListUserOrganizations(context.Context, string, CursorPageOptions) (ListResult[OrganizationIdentity], error)
}
type UserPinnedItemReader ¶ added in v1.0.0
type UserProfileReader ¶ added in v1.0.0
UserProfileReader reads one exact public or viewer-visible profile header.
type UserRepositoryOptions ¶ added in v1.0.0
type UserRepositoryOptions struct {
Relationship string
Sort string
Direction string
After string
PageOptions
}
type UserRepositoryReader ¶ added in v1.0.0
type UserRepositoryReader interface {
ListUserRepositories(context.Context, string, UserRepositoryOptions) (ListResult[Repository], error)
}
UserRepositoryReader reads one bounded page of repositories related to a user. Contributed relationships require the GraphQL capability below.
type UserSearchOptions ¶ added in v1.0.0
type UserSearchResult ¶ added in v1.0.0
type UserSearcher ¶ added in v1.0.0
type UserSearcher interface {
SearchUsers(context.Context, UserSearchOptions) (UserSearchResult, error)
}
UserSearcher discovers GitHub account identities without hydrating every result profile.
type UserSocialAccountReader ¶ added in v1.0.0
type UserSocialAccountReader interface {
ListUserSocialAccounts(context.Context, string, PageOptions) (ListResult[SocialAccount], error)
}
UserSocialAccountReader reads one bounded page of public social accounts.