Documentation
¶
Overview ¶
Package githubapp authenticates to GitHub as the docz-api App and fetches a repo's docz content over the Git Trees API (no checkout). It is the concrete implementation of ingest.RepoFetcher.
Authentication uses the App JWT → installation-token flow via bradleyfalzon/ghinstallation, which signs a short-lived app JWT, exchanges it for an installation access token, and caches/refreshes that token transparently on every request.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCredentialsRejected = errors.New("github app credentials rejected")
ErrCredentialsRejected marks a self-check failure caused by the App credentials themselves — a malformed private key, or an app id and key that GitHub refuses. Such a failure is permanent: no amount of retrying fixes it, so callers should fail startup rather than serve with an App that can never ingest.
Failures that are *not* this (DNS, refused connections, timeouts, rate limits) are transient and must not take down an otherwise healthy API.
Functions ¶
This section is empty.
Types ¶
type AppIdentity ¶ added in v0.6.0
AppIdentity is what a successful self-check learned about the authenticated App. Logging it at startup turns "which App am I?" into an observable fact rather than an assumption about which secret got mounted.
func SelfCheck ¶ added in v0.6.0
func SelfCheck(ctx context.Context, appID int64, pemKey []byte, apiBase string) (*AppIdentity, error)
SelfCheck authenticates as the App itself and reads back its own identity.
It exists because the App credentials are otherwise exercised nowhere before the first ingest job: webhooks prove only that GitHub can reach us, and /readyz deliberately checks serving dependencies only (GitHub being down must not pull the read API out of rotation). Without this, a mangled private key surfaced as retries that failed silently and then blocked the repo (INV-0007 F5). Here it surfaces once, at boot, naming the cause.
Unlike NewClient this uses an *app* JWT rather than an installation token, so it needs no installation id and can run before any repo is onboarded.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client fetches repo docz content from GitHub as one App installation. It satisfies ingest.RepoFetcher.
func NewClient ¶
NewClient builds a Client authenticated as the given installation. pemKey is the PEM-encoded RSA app private key; apiBase overrides the GitHub API root for GitHub Enterprise ("" or the public root uses api.github.com).
func (*Client) Fetch ¶
Fetch resolves the default-branch HEAD, pulls the recursive tree, and fetches .docz.yaml, the configured changelog and landing-page files when present, every doc blob matching the docz filename convention, and — when the api: block is enabled — every .md under docs_dir plus each present additional_docs file (DESIGN-0004). Precise filtering (per-type assignment, api exclusions, page classification) is left to ingest, which has the parsed config; githubapp only decides what to fetch.
Source Files