github

Documentation

Overview

Package github provides server-side GitHub App authentication, rate limit monitoring, and reachability probing.

Index

• func ExtractRateLimitHeaders(resp *http.Response, appName, caller string)
• type AppConfig
• type AppTokenProvider
  • func NewAppTokenProvider(appName string, appID int64, privateKey *rsa.PrivateKey, apiURL string, ...) *AppTokenProvider
  • func (p *AppTokenProvider) GenerateAppJWT() (string, error)
  • func (p *AppTokenProvider) GetGrantedPermissions(scope string) map[string]string
  • func (p *AppTokenProvider) GetInstallationID(ctx context.Context, scope string) (int64, error)
  • func (p *AppTokenProvider) GetInstallationToken(ctx context.Context, scope string, permissions map[string]string, ...) (string, error)
• type PermissionDiffEntry
  • func DiffPermissions(requested, granted map[string]string) []PermissionDiffEntry
• type RateLimitPoller
  • func NewRateLimitPoller(apps map[string]AppConfig, apiURL string, interval time.Duration) *RateLimitPoller
  • func (p *RateLimitPoller) Start()
  • func (p *RateLimitPoller) Stop()
• type ReachabilityProber
  • func NewReachabilityProber(apps map[string]AppConfig, apiURL string, interval time.Duration) *ReachabilityProber
  • func (p *ReachabilityProber) Start()
  • func (p *ReachabilityProber) Stop()

Functions

func ExtractRateLimitHeaders

func ExtractRateLimitHeaders(resp *http.Response, appName, caller string)

ExtractRateLimitHeaders reads GitHub rate limit headers from an HTTP response and updates Prometheus gauges. Also detects rate limit exceeded conditions on 403 responses.

Types

type AppConfig

type AppConfig struct {
	AppID         int64
	PrivateKey    *rsa.PrivateKey
	OrgPolicyRepo string
}

AppConfig holds the configuration for a GitHub App.

type AppTokenProvider

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

AppTokenProvider creates permission-scoped GitHub installation tokens for the server-side exchange flow.

func NewAppTokenProvider

func NewAppTokenProvider(appName string, appID int64, privateKey *rsa.PrivateKey, apiURL string, httpClient *http.Client) *AppTokenProvider

NewAppTokenProvider creates a server-side AppTokenProvider.

func (*AppTokenProvider) GenerateAppJWT

func (p *AppTokenProvider) GenerateAppJWT() (string, error)

GenerateAppJWT returns a short-lived JWT for authenticating as the GitHub App. The signed token is cached for 9 minutes (valid for 10) to avoid redundant RSA signing operations under load.

func (*AppTokenProvider) GetGrantedPermissions

func (p *AppTokenProvider) GetGrantedPermissions(scope string) map[string]string

GetGrantedPermissions returns the cached set of permissions actually granted to this app's installation on the given org, or nil if no installation has been resolved yet (or the entry has expired). It does NOT trigger a fetch — call GetInstallationID first if needed.

func (*AppTokenProvider) GetInstallationID

func (p *AppTokenProvider) GetInstallationID(ctx context.Context, scope string) (int64, error)

GetInstallationID resolves the GitHub App installation ID for the given scope. Only org-level resolution is supported (no repo-level fallback). Concurrent requests for the same org are deduplicated via singleflight.

func (*AppTokenProvider) GetInstallationToken

func (p *AppTokenProvider) GetInstallationToken(ctx context.Context, scope string, permissions map[string]string, repositories []string, caller string) (string, error)

GetInstallationToken creates a permission-scoped GitHub installation token.

type PermissionDiffEntry

type PermissionDiffEntry struct {
	Permission string `json:"permission"`
	Requested  string `json:"requested"`
	Granted    string `json:"granted,omitempty"` // empty if not granted at all
	Status     string `json:"status"`            // ok | insufficient | missing | unknown
}

PermissionDiffEntry describes how a single requested permission compares to what the installation actually has.

func DiffPermissions

func DiffPermissions(requested, granted map[string]string) []PermissionDiffEntry

DiffPermissions compares requested permissions against what was granted on the installation. It returns one entry per requested permission, ordered by permission name. Status is:

• "ok": granted level meets or exceeds requested
• "insufficient": granted but at a lower level (e.g. read < write)
• "missing": permission not granted at all on the installation
• "unknown": granted permissions are not known (e.g. installation cache miss)

If granted is nil (cache miss / never resolved), every entry is "unknown" rather than "missing", so the operator isn't misled.

type RateLimitPoller

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

RateLimitPoller periodically polls GitHub rate limit endpoints for all app installations. Self-contained — manages its own JWT signing and token cache, isolated from the exchange-path AppTokenProvider.

func NewRateLimitPoller

func NewRateLimitPoller(apps map[string]AppConfig, apiURL string, interval time.Duration) *RateLimitPoller

NewRateLimitPoller creates a rate limit poller.

func (*RateLimitPoller) Start

func (p *RateLimitPoller) Start()

Start begins the polling loop in a background goroutine.

func (*RateLimitPoller) Stop

func (p *RateLimitPoller) Stop()

Stop halts the polling loop.

type ReachabilityProber

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

ReachabilityProber periodically probes GitHub API endpoints to verify connectivity. Results are exported as Prometheus gauges.

func NewReachabilityProber

func NewReachabilityProber(apps map[string]AppConfig, apiURL string, interval time.Duration) *ReachabilityProber

NewReachabilityProber creates a reachability prober.

func (*ReachabilityProber) Start

func (p *ReachabilityProber) Start()

Start begins the probing loop in a background goroutine.

func (*ReachabilityProber) Stop

func (p *ReachabilityProber) Stop()

Stop halts the probing loop.