GhEx.JWT (gh_ex v0.1.0)

Copy Markdown View Source

Mints the short-lived JWT a GitHub App presents to authenticate as itself.

The token is signed RS256 (RSASSA-PKCS1-v1_5 over SHA-256) with the app's private key. That single, well-understood algorithm is handled by OTP's :public_key and :crypto directly, so no JOSE dependency is pulled in.

GitHub's rules, encoded as the defaults here:

  • iss is the app's client id (preferred) or numeric app id.
  • iat is set :skew seconds in the past to tolerate clock drift between this machine and GitHub (default 60).
  • exp is iat + :lifetime, kept under GitHub's 10-minute ceiling (default 540 seconds, so the exp - iat span is well under 600).

This is the credential used to mint installation tokens; see GhEx.App.

Summary

Functions

mint(issuer, pem, opts \\ [])

Mints a signed GitHub App JWT.

Functions

mint(issuer, pem, opts \\ [])

@spec mint(String.t() | integer(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, :invalid_pem | {:invalid_lifetime, integer()}}

Mints a signed GitHub App JWT.

issuer is the app's client id or numeric app id. pem is the app private key in PEM form, exactly as GitHub provides it.

Returns {:ok, jwt}, or {:error, reason} when the PEM cannot be decoded (:invalid_pem) or :lifetime exceeds GitHub's 600-second ceiling ({:invalid_lifetime, lifetime}).

Options

  • :now - the current unix time in seconds. Defaults to the system clock; pass it in tests for a deterministic token.
  • :skew - seconds to backdate iat. Defaults to 60.
  • :lifetime - seconds from iat to exp. Defaults to 540. Must not exceed 600; GitHub rejects a longer-lived JWT.