github

Documentation

Overview

Package github provides a GitHub API client for fetching releases and assets.

Index

• Constants
• func BinaryAssetPatterns(name, goos, goarch string) []string
• func MatchAssetPattern(assetName, pattern string) bool
• func ParseSource(source string) (owner, repo, version string, err error)
• type Asset
• type Client
  • func NewClient() *Client
  • func NewClientForTest(httpClient *http.Client, baseURL string) *Client
  • func NewClientForTestWithHosts(httpClient *http.Client, baseURL string, hosts ...string) *Client
  • func NewClientWithBaseURL(baseURL string) (*Client, error)
  • func (c *Client) DownloadAsset(ctx context.Context, assetURL, destPath string) error
  • func (c *Client) FetchLatestRelease(ctx context.Context, owner, repo string) (*Release, error)
  • func (c *Client) FetchRelease(ctx context.Context, owner, repo, tag string) (*Release, error)
  • func (c *Client) FindBinaryAsset(release *Release, componentName, goos, goarch string) (*Asset, string, error)
  • func (c *Client) FindSigstoreBundle(release *Release, binaryAssetName string) (*Asset, error)
  • func (c *Client) ListReleases(ctx context.Context, owner, repo string) ([]Release, error)
• type Release

Constants

const (
	// DefaultRateLimit is the default maximum requests per second.
	// This is conservative to avoid hitting GitHub's secondary rate limits.
	DefaultRateLimit = 10

	// DefaultRateBurst is the default burst size for rate limiting.
	// Allows short bursts while maintaining the average rate.
	DefaultRateBurst = 5
)

Rate limiting configuration. GitHub API allows 60 requests/hour unauthenticated, 5000/hour authenticated. We use conservative defaults to avoid hitting limits in CI environments.

Functions

func BinaryAssetPatterns

func BinaryAssetPatterns(name, goos, goarch string) []string

BinaryAssetPatterns returns possible asset name patterns for a component.

func MatchAssetPattern

func MatchAssetPattern(assetName, pattern string) bool

MatchAssetPattern checks if an asset name matches a pattern. Handles optional extensions like .exe, .tar.gz, .zip.

func ParseSource

func ParseSource(source string) (owner, repo, version string, err error)

ParseSource parses a source string like "owner/repo@version". Returns owner, repo, version constraint. SECURITY: Validates that owner and repo are valid GitHub slugs to prevent path smuggling attacks where malicious values like "owner/../../repos/victim/repo" could manipulate API request paths.

Types

type Asset

type Asset struct {
	Name               string `json:"name"`
	BrowserDownloadURL string `json:"browser_download_url"`
	Size               int64  `json:"size"`
}

Asset represents a GitHub release asset.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client fetches releases and assets from GitHub.

func NewClient

func NewClient() *Client

NewClient returns a client using GITHUB_TOKEN from environment. Uses the default GitHub API endpoint (api.github.com).

func NewClientForTest

func NewClientForTest(httpClient *http.Client, baseURL string) *Client

NewClientForTest creates a Client with custom httpClient and baseURL for testing. This bypasses the trusted host validation to allow mock servers. Sets allowLoopbackHTTP to permit HTTP to localhost for test servers. SECURITY: Auth tokens are NEVER sent over HTTP, even in tests. Only use in test files.

func NewClientForTestWithHosts

func NewClientForTestWithHosts(httpClient *http.Client, baseURL string, hosts ...string) *Client

NewClientForTestWithHosts creates a Client for testing with additional trusted hosts. This is useful when testing with mock servers that need to be in the trusted hosts list. SECURITY: Auth tokens are NEVER sent over HTTP, even in tests. Only use in test files.

func NewClientWithBaseURL

func NewClientWithBaseURL(baseURL string) (*Client, error)

NewClientWithBaseURL creates a client with a custom base URL. The base URL must be HTTPS and on a trusted API host. HTTP is only allowed for localhost/127.0.0.1 (for testing), and tokens are NEVER sent over HTTP connections regardless of destination. This is primarily for testing with mock servers.

func (*Client) DownloadAsset

func (c *Client) DownloadAsset(ctx context.Context, assetURL, destPath string) error

DownloadAsset downloads an asset to the specified path. Only sends auth headers to trusted GitHub hosts over HTTPS. Validates redirect destinations against the allowlist. Enforces maximum download size to prevent disk exhaustion. SECURITY: HTTP is rejected for all URLs. Only HTTPS is allowed. The allowLoopbackHTTP flag (test-only) permits HTTP to localhost/127.0.0.1 but NEVER sends auth headers over HTTP.

func (*Client) FetchLatestRelease

func (c *Client) FetchLatestRelease(ctx context.Context, owner, repo string) (*Release, error)

FetchLatestRelease fetches the latest release from owner/repo. SECURITY: All path segments are URL-escaped to prevent path/query injection.

func (*Client) FetchRelease

func (c *Client) FetchRelease(ctx context.Context, owner, repo, tag string) (*Release, error)

FetchRelease fetches a specific release by tag from owner/repo. SECURITY: All path segments are URL-escaped to prevent path/query injection.

func (*Client) FindBinaryAsset

func (c *Client) FindBinaryAsset(release *Release, componentName, goos, goarch string) (*Asset, string, error)

FindBinaryAsset finds the binary asset for a specific platform. Returns a copy of the asset and its base name (without platform suffix). Returns a copy to avoid pointer aliasing issues if the release is modified.

func (*Client) FindSigstoreBundle

func (c *Client) FindSigstoreBundle(release *Release, binaryAssetName string) (*Asset, error)

FindSigstoreBundle finds the .sigstore.json bundle for a binary asset. Returns a copy to avoid pointer aliasing issues if the release is modified.

func (*Client) ListReleases

func (c *Client) ListReleases(ctx context.Context, owner, repo string) ([]Release, error)

ListReleases fetches all releases from owner/repo (up to 100). SECURITY: All path segments are URL-escaped to prevent path/query injection.

type Release

type Release struct {
	TagName string  `json:"tag_name"`
	Assets  []Asset `json:"assets"`
}

Release represents a GitHub release.