Documentation
¶
Overview ¶
Package github provides a client for interacting with the GitHub API to generate installation access tokens for GitHub Apps.
The client uses google/go-github for typed API calls, handles GitHub App JWT authentication, and caches installation IDs to minimize API calls.
Index ¶
- Constants
- Variables
- type APIError
- type Client
- func (c *Client) GetContents(ctx context.Context, repository string, path string) ([]byte, error)
- func (c *Client) RateLimit(ctx context.Context, token string) (RateLimitInfo, error)
- func (c *Client) RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)
- func (c *Client) RevokeToken(ctx context.Context, token string) error
- type ClientIface
- type MockClient
- func (m *MockClient) GetContents(ctx context.Context, repository string, path string) ([]byte, error)
- func (m *MockClient) RateLimit(ctx context.Context, token string) (RateLimitInfo, error)
- func (m *MockClient) RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)
- func (m *MockClient) RevokeToken(ctx context.Context, token string) error
- type NetworkError
- type Options
- type RateLimitInfo
- type RetryConfig
- type TokenRequest
- type TokenResponse
Constants ¶
const ( // DefaultBaseURL is the GitHub API base URL when no custom endpoint is set. DefaultBaseURL = "https://api.github.com" // DefaultTimeout is the HTTP client timeout for GitHub API requests. DefaultTimeout = 30 * time.Second // DefaultTokenReadyDelay is the pause between minting an installation // token and first using it. GitHub's edge infrastructure needs time to // replicate new tokens; without a delay, the first request frequently // receives a transient 403 "Resource not accessible by integration". // Per GitHub Support guidance, 2-3 seconds prevents the majority of // replication-lag errors. DefaultTokenReadyDelay = 2 * time.Second )
Variables ¶
var ( // ErrInvalidRepository is returned when the repository string is not in "owner/repo" format. ErrInvalidRepository = errors.New("invalid repository format (expected owner/repo)") // ErrFileNotFound is returned when the requested file path does not exist or is a directory. ErrFileNotFound = errors.New("file not found") // ErrRepositoryNotFound is returned when the repository is not // installed or not accessible to the app. ErrRepositoryNotFound = errors.New("repository not found or not accessible") // ErrInstallationNotFound is returned when no GitHub App installation // exists for the given owner (organization or user). ErrInstallationNotFound = errors.New("installation not found for owner") )
var DefaultRetryConfig = &RetryConfig{ MaxAttempts: 4, InitialBackoff: 2 * time.Second, MaxBackoff: 10 * time.Second, Multiplier: 2.0, JitterFraction: 0.1, }
DefaultRetryConfig provides sensible retry defaults for GitHub API calls. Timings follow GitHub Support guidance: new installation tokens may take seconds to replicate, so we use 2s / 10s / 30s retry windows.
var New = newClient
New is the constructor for the GitHub client. It is a package-level variable so tests can replace it.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
// contains filtered or unexported fields
}
APIError represents a non-2xx HTTP response from the GitHub API.
func (*APIError) StatusCode ¶
StatusCode returns the HTTP status code from the GitHub API response.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client manages GitHub API interactions for token generation.
func (*Client) GetContents ¶
func (*Client) RequestToken ¶
func (c *Client) RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)
type ClientIface ¶
type ClientIface interface {
// RequestToken requests an installation access token scoped to
// the given repository and permissions.
// req.Repository must be in "owner/repo" format. Returns error for invalid repo or API failure.
RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)
// RevokeToken revokes an installation access token, rendering it unusable.
// The token parameter is used to authenticate the DELETE /installation/token call.
RevokeToken(ctx context.Context, token string) error
// RateLimit returns current rate limit status. The /rate_limit endpoint does not consume quota.
RateLimit(ctx context.Context, token string) (RateLimitInfo, error)
// GetContents fetches file content from repository at path. Repository must be "owner/repo".
// Returns error if the path is not found, is a directory, or the API call fails.
GetContents(ctx context.Context, repository string, path string) ([]byte, error)
}
ClientIface defines the GitHub App client operations for token issuance and repository access. Implementations must be safe for concurrent use.
type MockClient ¶
MockClient is a testify mock implementing ClientIface.
func (*MockClient) GetContents ¶
func (*MockClient) RateLimit ¶
func (m *MockClient) RateLimit(ctx context.Context, token string) (RateLimitInfo, error)
func (*MockClient) RequestToken ¶
func (m *MockClient) RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)
func (*MockClient) RevokeToken ¶
func (m *MockClient) RevokeToken(ctx context.Context, token string) error
type NetworkError ¶
type NetworkError struct {
// contains filtered or unexported fields
}
NetworkError represents a network-level error (retryable).
func (*NetworkError) Error ¶
func (e *NetworkError) Error() string
Error returns the error string representation of the network error.
func (*NetworkError) Unwrap ¶
func (e *NetworkError) Unwrap() error
Unwrap returns the underlying error wrapped by NetworkError.
type Options ¶
type Options struct {
BaseURL string
ClientID string // GitHub App Client ID (used as JWT issuer)
PrivateKey string `json:"-"` // PEM-encoded RSA private key
Timeout time.Duration
}
Options configures the GitHub App client.
type RateLimitInfo ¶
RateLimitInfo contains rate limit information from the GitHub API.
type RetryConfig ¶
type RetryConfig struct {
MaxAttempts int
InitialBackoff time.Duration
MaxBackoff time.Duration
Multiplier float64
JitterFraction float64
}
RetryConfig defines retry behavior for GitHub API HTTP calls.
type TokenRequest ¶
TokenRequest represents a request for an installation access token.
type TokenResponse ¶
TokenResponse represents the GitHub API response for an installation access token.