GitHubEx

Hex.pmHexDocsGitHubLicense

GitHubEx

Native Elixir SDK for the GitHub REST API, generated from the pinned official GitHub OpenAPI description and executed through the shared pristine runtime.

The SDK already exposes the full pinned REST surface. The hard part is choosing the right credential for the endpoint you want to call. This repo now ships a generated Auth Capability Matrix so that auth guidance comes from committed data instead of memory.

Normal request-surface generation now flows through codegen/github_ex/codegen/provider.ex, the OpenAPI source plugin, the GitHub auth plugin, and the shared pristine_codegen compiler. Generated modules build request maps, hand them to the generated-request bridge inside GitHubEx.Client, and ultimately execute through Pristine.execute_request/3, with compiler-emitted stream_* wrappers for paginated endpoints.

Authentication Start Here

1. I want to run the bundled examples today

Use a fine-grained PAT.

Read Authentication and OAuth, Auth Capability Matrix, and Examples README.

2. I want to explore the SDK broadly from local scripts

Start with the Auth Capability Matrix.

If you want to roam across many modules, multiple organizations, packages, checks, or enterprise-flavored surfaces, a classic PAT is often the simpler local-development credential. It is broader and less safe, but GitHub still documents real fine-grained PAT gaps and this repo does not hide that anymore.

Read Authentication and OAuth.

3. My app needs a browser approval screen and callback code

Use an OAuth app when you need GitHub to send a user through an approval screen and redirect back with an authorization code. OAuth also still matters for some enterprise-object access.

Read Authentication and OAuth.

4. I need installed repo or org automation with short-lived bot tokens

Use a GitHub App.

Keep these credentials distinct:

Read GitHub App Authentication and the Auth Capability Matrix.

5. Enterprise-object access note

If you need enterprise-object access, read the OAuth section first. GitHub still documents that as a real reason OAuth can remain the better fit.

Install

def deps do
  [
    {:github_ex, "~> 0.1.0"}
  ]
end
mix deps.get

For active local development beside sibling checkouts, github_ex can also be consumed from a relative path:

{:github_ex, path: "../github_ex"}

Inside this repo, the shared pristine dependencies now resolve by one stable policy:

That removes the need for a committed vendored deps/ tree while keeping local development and downstream dependency behavior aligned.

Make One Request

Create a client with a bearer token:

client = GitHubEx.Client.new(auth: System.fetch_env!("GITHUB_TOKEN"))

Fetch the authenticated user:

{:ok, me} = GitHubEx.Users.get_authenticated(client)

List repositories for that user:

{:ok, repos} =
  GitHubEx.Repos.list_for_authenticated_user(client, %{
    "visibility" => "all",
    "per_page" => 50
  })

Ask for a wrapped response when you need headers, rate-limit information, or pagination links:

{:ok, wrapped} =
  GitHubEx.Client.request(client, %{
    method: :get,
    path: "/user",
    opts: [response: :wrapped]
  })

wrapped.data
wrapped.rate_limit
wrapped.links["next"]

Authentication Modes

GitHubEx.Client.new/1 supports:

Use the generated Auth Capability Matrix to check a specific REST operation before assuming one token type covers it.

Docs Map

Examples Map

Pinned Upstream Contract

This repo is currently pinned to:

GitHub currently reports supported REST API versions 2026-03-10 and 2022-11-28 from https://api.github.com/versions. This SDK intentionally pins 2026-03-10 instead of silently drifting.

Verification

mix github.generate delegates to the shared compiler and refreshes the final committed artifact contract:

mix github.generate
mix format
mix compile --warnings-as-errors
mix test
mix credo --strict
mix dialyzer
mix docs