go-githubauth

GitHub authentication for Go, exposed as standard oauth2.TokenSource implementations: GitHub App JWTs, installation tokens, and personal access tokens. Depends only on golang-jwt/jwt and golang.org/x/oauth2 — no GitHub SDK required.

Installation

go get github.com/jferrl/go-githubauth

Requires Go 1.26+.

Quick start

Authenticating as a GitHub App is a two-step chain: an RS256 JWT identifies the App, and it is exchanged for an installation token scoped to one installation. Both sources cache their tokens and refresh them proactively.

privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY"))
clientID := os.Getenv("GITHUB_APP_CLIENT_ID") // e.g. "Iv1.1234567890abcdef"
installationID, _ := strconv.ParseInt(os.Getenv("GITHUB_INSTALLATION_ID"), 10, 64)

appTokenSource, err := githubauth.NewApplicationTokenSource(clientID, privateKey)
if err != nil {
	log.Fatal(err)
}
installationTokenSource := githubauth.NewInstallationTokenSource(installationID, appTokenSource)

// Every request carries a valid installation token; refresh is automatic.
// Works standalone or with any SDK that accepts an *http.Client, e.g.
// github.NewClient(httpClient) from google/go-github.
httpClient := oauth2.NewClient(context.Background(), installationTokenSource)

NewApplicationTokenSource accepts a string Client ID (recommended by GitHub) or an int64 App ID (legacy) — the type is inferred from the argument. Runnable examples for every constructor live on pkg.go.dev.

Features

• oauth2.TokenSource implementations for GitHub App JWTs, installation tokens, and personal access tokens (classic and fine-grained)
• Token caching with proactive refresh: tokens regenerate 30s before expiry, eliminating in-flight 401s (tunable via WithExpirySkew / WithInstallationExpirySkew)
• JWT signing through the standard crypto.Signer interface, so the private key can live in AWS KMS, GCP KMS, Azure Key Vault, Vault Transit, a PKCS#11 HSM, or ssh-agent
• Webhook delivery verification (X-Hub-Signature-256, constant-time) with ready-made http.Handler middleware
• GitHub Enterprise Server and GitHub Enterprise Cloud (data residency) support
• Automatic single retry on throttled responses (WithRetryOnThrottle, enabled by default)
• Typed errors to branch on: RateLimitError (with RetryAfter) for a throttled request, APIError (with StatusCode) for every other rejection
• A githubauth CLI with a documented exit code per failure class and --exec, which passes the credential to a command without printing it
• Two dependencies total: golang-jwt/jwt and golang.org/x/oauth2

Used by

Project
Kargo	Application lifecycle orchestration
Terraform GitHub provider	The Terraform provider built and run by GitHub
gno	Go virtual machine and blockchain behind gno.land
Updatecli	Declarative update policy engine
Sippy	Dashboards for OpenShift CI test and job data

Full list on pkg.go.dev.

Command line

The same credentials, without writing Go:

brew install jferrl/tap/githubauth

Or download a binary from the latest release — Linux, macOS and Windows, on amd64 and arm64 — or build it yourself:

go install github.com/jferrl/go-githubauth/cmd/githubauth@latest

githubauth token --client-id Iv1.abc --key app.pem --installation 12345

The token goes to stdout and nothing else does, so it composes:

curl -H "Authorization: Bearer $(githubauth token)" \
  https://api.github.com/installation/repositories

Every flag falls back to an environment variable — GITHUB_APP_CLIENT_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID — so a configured CI step is just githubauth token. --key takes a file path, the PEM itself, or - to read stdin, which keeps the key off disk:

vault kv get -field=pem secret/github-app |
  githubauth token --key - --installation 12345

githubauth jwt prints the App JWT for the few endpoints that need one, --json adds the expiry, and --repos scopes the token to named repositories. Run githubauth help for the rest.

Keeping the token out of your logs

A printed credential stays valid for an hour, in every place your output landed: a CI log, a terminal scrollback, a coding agent's transcript. --exec runs a command with the token in its $GITHUB_TOKEN and prints it nowhere, exiting with whatever the command exited with:

githubauth token --installation 12345 --exec -- gh pr list

Exit codes

Scripts and agents branch on the code rather than on the message:

Code	Meaning
0	a credential was printed
1	something else failed, retrying may help
2	the invocation is wrong
3	GitHub refused the key or the App's permissions
4	rate limited, wait and repeat
5	the App is not installed where it was asked to be

Under --json, or when a coding agent is detected, a failure is one JSON document on stdout — {"type":"githubauth.error","schema_version":"1","error":{...}}, carrying exit_code, status_code, retry_after_seconds and suggestions — and stderr stays empty. Detection reads the usual agent variables (CLAUDECODE, CURSOR_AGENT, and friends); GITHUBAUTH_AGENT_MODE or --agent/--agent=false overrides it, and a test suite that shells out to the CLI should set GITHUBAUTH_AGENT_MODE=0. The success output never changes: a bare token stays a bare token, so $(githubauth token) means the same thing everywhere. AGENTS.md has the full contract.

Comparison with ghinstallation

ghinstallation is the long-standing library in this space and works well. The core difference is the integration model: ghinstallation is an http.RoundTripper you install as an HTTP transport, while go-githubauth implements oauth2.TokenSource, so credentials compose with anything that speaks oauth2 — oauth2.NewClient, go-github, gRPC per-RPC credentials, or code that just needs the token string.

	go-githubauth	ghinstallation
Integration model	oauth2.TokenSource	http.RoundTripper
Dependencies	golang-jwt/jwt, x/oauth2	golang-jwt/jwt, google/go-github
App identifiers	Client ID (string, recommended by GitHub) and App ID (int64)	App ID (int64)
Token refresh	Proactive, tunable (WithExpirySkew, default 30s)	Proactive, fixed 1 minute
External signers (KMS/HSM)	Standard crypto.Signer — existing KMS adapters plug in directly	Library-specific Signer interface
Webhook signature verification	Included (webhook subpackage)	Not included
Personal access tokens	Included	Not included
GitHub Enterprise	WithEnterpriseURL (GHES) and WithBaseURL (GHEC data residency)	BaseURL field

If ghinstallation already fits your setup, there is no urgent reason to switch. Choose go-githubauth when you want oauth2-native composition, Client ID support, KMS-backed signing through the standard crypto.Signer interface, or a smaller dependency tree.

Personal access tokens

tokenSource := githubauth.NewPersonalAccessTokenSource(os.Getenv("GITHUB_TOKEN"))
httpClient := oauth2.NewClient(context.Background(), tokenSource)

Works with both classic (ghp_...) and fine-grained (github_pat_...) tokens.

GitHub Enterprise

• WithEnterpriseURL — GitHub Enterprise Server (GHES). The URL is normalized the way GHES expects, appending /api/v3/ when needed.
• WithBaseURL — the URL is used verbatim. Fits GitHub Enterprise Cloud with data residency (https://api.SUBDOMAIN.ghe.com/) or an httptest server in tests.

githubauth.NewInstallationTokenSource(installationID, appTokenSource,
	githubauth.WithEnterpriseURL("https://github.example.com"))

githubauth.NewInstallationTokenSource(installationID, appTokenSource,
	githubauth.WithBaseURL("https://api.octocorp.ghe.com"))

Options combine in any order. An unparseable URL (or a nil client passed to WithHTTPClient) is reported by the first Token() call instead of silently falling back to the public GitHub API.

Proactive token refresh

oauth2.ReuseTokenSource refreshes a cached token only after it expires, so a request that starts just before expiry can reach GitHub with a dead credential and 401. Both constructors instead wrap their sources in ReuseTokenSourceWithSkew, refreshing when time.Until(exp) <= skew (default DefaultExpirySkew, 30s).

appTokenSource, err := githubauth.NewApplicationTokenSource(clientID, privateKey,
	githubauth.WithApplicationTokenExpiration(5*time.Minute),
	githubauth.WithExpirySkew(5*time.Second), // effective validity: 3m55s
)

Expiration is backdated 60s for clock drift, so effective validity is expiration - 60s - skew. Values at or below 90s (the backdate plus DefaultExpirySkew) are rejected and fall back to 10 minutes, because below that the cache can never hold the token and every call re-signs.

A zero or negative skew restores exact oauth2.ReuseTokenSource behavior. The wrapper is exported as ReuseTokenSourceWithSkew for use with any third-party oauth2.TokenSource, and is safe for concurrent use.

Signing with external key stores (KMS, HSM, Vault)

NewApplicationTokenSourceFromSigner accepts any RSA-backed crypto.Signer, so the App private key never touches process memory. GitHub requires RS256; non-RSA signers are rejected at construction time.

// signer: *rsa.PrivateKey, or a wrapper for AWS KMS, GCP KMS, Azure Key
// Vault, Vault Transit, a PKCS#11 HSM, or ssh-agent.
appTokenSource, err := githubauth.NewApplicationTokenSourceFromSigner(clientID, signer)

All major backends support the required RSASSA_PKCS1_V1_5_SHA_256 operation: AWS KMS, GCP KMS, Azure Key Vault, Vault Transit, and PKCS#11 via crypto11. Community crypto.Signer adapters: form3tech-oss/jwt-go-aws-kms, salrashid123/signer.

Webhook verification

The webhook subpackage verifies the X-Hub-Signature-256 header (HMAC-SHA256, constant time) and ships middleware that restores the body for downstream handlers. Failed verifications short-circuit with 401; oversized bodies return 413.

secret := []byte(os.Getenv("GITHUB_WEBHOOK_SECRET"))

mux := http.NewServeMux()
mux.HandleFunc("/webhook", handleWebhook) // body is already authenticated here

log.Fatal(http.ListenAndServe(":8080", webhook.Middleware(secret)(mux)))

Options: webhook.WithMaxPayloadSize(n) (default 25 MiB, GitHub's delivery cap) and webhook.WithErrorHandler(fn).

Outside net/http (Lambda, queues), use webhook.Verify directly:

if err := webhook.Verify(secret, body, signature); err != nil {
	// branch with errors.Is: webhook.ErrMissingSignature,
	// webhook.ErrInvalidSignatureFormat, webhook.ErrSignatureMismatch
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub. If this package is useful to you, a star helps others discover it.

License

This project is licensed under the MIT License. See the LICENSE file for details.