Documentation
¶
Overview ¶
Package github provides GitHub API integration for Previewd.
This package implements a client for interacting with the GitHub API to fetch pull request metadata and update commit statuses.
Key features:
- Fetch pull request details (title, author, SHA, branches)
- Update commit status with preview environment information
- Retry logic with exponential backoff
- Rate limit handling
- Error handling and logging
Authentication:
The client requires a GitHub personal access token with the following scopes:
- repo (for accessing private repositories)
- repo:status (for updating commit status)
Example usage:
client := github.NewClient(token)
// Fetch pull request metadata
pr, err := client.GetPullRequest(ctx, "owner", "repo", 123)
if err != nil {
log.Fatal(err)
}
fmt.Printf("PR #%d: %s\n", pr.Number, pr.Title)
// Update commit status
status := &github.CommitStatus{
State: "success",
TargetURL: "https://pr-123.preview.example.com",
Description: "Preview environment ready",
Context: "previewd",
}
err = client.UpdateCommitStatus(ctx, "owner", "repo", pr.SHA, status)
if err != nil {
log.Fatal(err)
}
Rate Limiting:
The GitHub API has rate limits:
- 5,000 requests per hour for authenticated requests
- 60 requests per hour for unauthenticated requests
The client automatically handles rate limit errors by waiting and retrying.
Retry Logic:
Failed requests are retried with exponential backoff:
- Initial backoff: 1 second
- Maximum backoff: 60 seconds
- Maximum retries: 3
- Backoff factor: 2.0
Retries are performed for transient errors (network issues, rate limits, 5xx errors). Client errors (4xx except 429) are not retried.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// GetPullRequest retrieves metadata about a pull request
GetPullRequest(ctx context.Context, owner, repo string, number int) (*PullRequest, error)
// GetPRFiles retrieves the list of files changed in a pull request
GetPRFiles(ctx context.Context, owner, repo string, number int) ([]*File, error)
// UpdateCommitStatus updates the status of a commit
UpdateCommitStatus(ctx context.Context, owner, repo, sha string, status *Status) error
}
Client interface defines the contract for interacting with GitHub API
type File ¶
type File struct {
Filename string
Status string
Patch string
Additions int
Deletions int
Changes int
}
File represents a file changed in a pull request
type PullRequest ¶
type PullRequest struct {
CreatedAt time.Time
UpdatedAt time.Time
Title string
Description string
HeadSHA string
BaseBranch string
HeadBranch string
Author string
State string
Labels []string
Number int
}
PullRequest represents GitHub pull request metadata
type RetryConfig ¶
type RetryConfig struct {
MaxRetries int
InitialBackoff time.Duration
MaxBackoff time.Duration
BackoffFactor float64
}
RetryConfig defines the retry behavior for API calls
type Status ¶
type Status struct {
State StatusState // pending, success, error, failure
TargetURL string // URL for more details
Description string // Short description of the status
Context string // A unique name for this status check
}
Status represents a commit status to be set on GitHub
type StatusState ¶
type StatusState string
StatusState represents the state of a commit status
const ( // StatusStatePending indicates that the status is pending StatusStatePending StatusState = "pending" // StatusStateSuccess indicates that the status succeeded StatusStateSuccess StatusState = "success" // StatusStateError indicates that the status errored StatusStateError StatusState = "error" // StatusStateFailure indicates that the status failed StatusStateFailure StatusState = "failure" )
Source Files