github

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: May 26, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

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

View Source
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

View Source
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")
)
View Source
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.

View Source
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) Error

func (e *APIError) Error() string

Error returns the formatted error message including the HTTP status code.

func (*APIError) StatusCode

func (e *APIError) StatusCode() int

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 (c *Client) GetContents(ctx context.Context, repository string, path string) ([]byte, error)

func (*Client) RateLimit

func (c *Client) RateLimit(ctx context.Context, token string) (RateLimitInfo, error)

func (*Client) RequestToken

func (c *Client) RequestToken(ctx context.Context, req *TokenRequest) (*TokenResponse, error)

func (*Client) RevokeToken

func (c *Client) RevokeToken(ctx context.Context, token string) 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

type MockClient struct {
	mock.Mock
}

MockClient is a testify mock implementing ClientIface.

func (*MockClient) GetContents

func (m *MockClient) GetContents(ctx context.Context, repository string, path string) ([]byte, error)

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

type RateLimitInfo struct {
	Remaining int
	ResetAt   time.Time
}

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

type TokenRequest struct {
	Repository  string
	Permissions map[string]string
}

TokenRequest represents a request for an installation access token.

type TokenResponse

type TokenResponse struct {
	Token     string
	ExpiresAt time.Time
}

TokenResponse represents the GitHub API response for an installation access token.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL