GitHub App authentication.
An app authenticates as itself with a JWT (see GhEx.JWT), built a client at a
time from {:app, issuer, pem} credentials:
app = GhEx.new(auth: {:app, client_id, File.read!("app.pem")})To act as an installation, the app mints a short-lived installation access token (valid one hour) and uses it as an ordinary bearer credential. There are two ways to get there:
installation/3returns a client that resolves and caches the token transparently, refreshing before it expires. This is the usual choice; it needs a runningGhEx.TokenCache.inst = GhEx.App.installation(app, installation_id, cache: GhEx.TokenCache.ETS) GhEx.REST.get(inst, "/installation/repositories")installation_client/3is the stateless primitive: it mints once and hands back a plain token-auth client plus theexpires_at, leaving the one-hour lifecycle to the caller.{:ok, inst, _expires_at} = GhEx.App.installation_client(app, installation_id) GhEx.REST.get(inst, "/installation/repositories")
Summary
Functions
Returns a client that authenticates as the installation, resolving its access
token through cache on demand and refreshing transparently before expiry.
Mints an installation token and returns a token-auth GhEx.Client that acts as
that installation, alongside the token's expires_at string.
Mints an installation access token, returning GitHub's full response body
("token", "expires_at", "permissions", "repository_selection", ...).
Functions
@spec installation(GhEx.Client.t(), integer() | String.t(), keyword()) :: GhEx.Client.t()
Returns a client that authenticates as the installation, resolving its access
token through cache on demand and refreshing transparently before expiry.
Construction does no I/O; the token is minted on the first request made with
the returned client. Requires a running GhEx.TokenCache (see
GhEx.TokenCache.ETS).
Options
:cache- required. AGhEx.TokenCachemodule, or a{module, ref}tuple naming a specific cache instance.:json- scopes the minted token to specificrepositories/permissions; different scopes cache under different keys.
@spec installation_client(GhEx.Client.t(), integer() | String.t(), keyword()) :: {:ok, GhEx.Client.t(), String.t() | nil} | {:error, term()}
Mints an installation token and returns a token-auth GhEx.Client that acts as
that installation, alongside the token's expires_at string.
The returned client inherits the app client's URLs and :req_options, so
GitHub Enterprise base URLs and any Req.Test plug carry over.
@spec installation_token(GhEx.Client.t(), integer() | String.t(), keyword()) :: {:ok, map()} | {:error, term()}
Mints an installation access token, returning GitHub's full response body
("token", "expires_at", "permissions", "repository_selection", ...).
app must be a client with {:app, ...} credentials. Pass :json to scope
the token to specific repositories or permissions.