README
¶
contextmatrix-githubauth
A small Go module providing GitHub authentication primitives shared by contextmatrix and contextmatrix-runner.
Overview
type TokenGenerator interface {
GenerateToken(ctx context.Context) (token string, expiresAt time.Time, err error)
}
Three implementations:
AppProvider— mints short-lived (~1h) installation access tokens from a GitHub App. Use this in production where possible.PATProvider— returns a static fine-grained personal access token with a sentinel "never refresh" expiry.CachingProvider— wraps anotherTokenGeneratorand amortizes minting across calls. Suitable for server-side use where every call uses the token immediately. Not recommended in places where the token is handed off to a long-lived consumer (see the contextmatrix-runner rationale).
Usage
import "github.com/mhersson/contextmatrix-githubauth"
// GitHub App
inner, err := githubauth.NewAppProvider(
appID, installationID, "/etc/secrets/github-app-key.pem",
githubauth.WithAPIBaseURL("https://api.github.com"),
)
if err != nil { /* ... */ }
provider := githubauth.NewCachingProvider(inner)
// Or PAT
inner, err := githubauth.NewPATProvider(os.Getenv("GH_TOKEN"))
provider := githubauth.NewCachingProvider(inner)
// Use it
token, _, err := provider.GenerateToken(ctx)
req.Header.Set("Authorization", "Bearer "+token)
Setup guides
For instructions on creating a GitHub App or fine-grained PAT and the permissions each consumer requires, see the contextmatrix GitHub auth setup guide.
License
MIT
Documentation
¶
Overview ¶
Package githubauth provides GitHub authentication primitives shared by the ContextMatrix server and the ContextMatrix runner. It exposes a TokenGenerator interface and three implementations: AppProvider for GitHub App credentials, PATProvider for fine-grained personal access tokens, and CachingProvider for amortizing App-token minting across calls.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppProvider ¶
type AppProvider struct {
// contains filtered or unexported fields
}
AppProvider mints short-lived installation access tokens for a GitHub App. Each call to GenerateToken signs a fresh JWT and exchanges it for an installation token via the GitHub REST API.
func NewAppProvider ¶
func NewAppProvider(appID, installationID int64, privateKeyPath string, opts ...Option) (*AppProvider, error)
NewAppProvider constructs an AppProvider by reading the PEM private key from disk.
func NewAppProviderWithKey ¶
func NewAppProviderWithKey(appID, installationID int64, key *rsa.PrivateKey, apiBaseURL string) (*AppProvider, error)
NewAppProviderWithKey constructs an AppProvider from an already-parsed RSA key and a custom API base URL. Intended for testing.
func (*AppProvider) GenerateToken ¶
GenerateToken signs a JWT, exchanges it via GitHub's REST API, and returns the resulting installation access token plus its expiry.
type CacheOption ¶
type CacheOption func(*CachingProvider)
CacheOption configures a CachingProvider.
func WithRefreshSkew ¶
func WithRefreshSkew(d time.Duration) CacheOption
WithRefreshSkew overrides the default 5-minute refresh window.
type CachingProvider ¶
type CachingProvider struct {
// contains filtered or unexported fields
}
CachingProvider wraps a TokenGenerator and reuses the most recent token until it is within RefreshSkew of expiry. Errors are not cached — the next call retries the inner provider.
func NewCachingProvider ¶
func NewCachingProvider(inner TokenGenerator, opts ...CacheOption) *CachingProvider
NewCachingProvider wraps inner with a cache.
func (*CachingProvider) GenerateToken ¶
GenerateToken returns the cached token if it has more than refreshSkew remaining; otherwise it asks the inner provider for a fresh one.
type Option ¶
type Option func(*AppProvider)
Option configures an AppProvider.
func WithAPIBaseURL ¶
WithAPIBaseURL overrides the GitHub API base URL. Trailing slashes are trimmed. An empty string is a no-op.
type PATProvider ¶
type PATProvider struct {
// contains filtered or unexported fields
}
PATProvider returns a static fine-grained personal access token.
func NewPATProvider ¶
func NewPATProvider(token string) (*PATProvider, error)
NewPATProvider constructs a PATProvider. Returns an error if token is empty.
func (*PATProvider) GenerateToken ¶
GenerateToken returns the configured PAT and a far-future expiry. The context is accepted for interface compatibility but unused.
Source Files