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.

• Resource owner: your user account if you want /user and /user/repos
• Repository access: only the selected repos you will test
• Minimal repository permissions: Metadata: read, Issues: read, Pull requests: read, Actions: read
• GET /user currently needs no fine-grained PAT permissions
• Contents: read is not required for the current bundled examples

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:

• app JWT: app-level authentication and installation-token exchange
• installation token: the default runtime credential for most repo and org API work
• app user token: user-attributed GitHub App access when the endpoint supports it

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.1"}
  ]
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:

• prefer sibling-relative paths when local checkouts exist for normal compile, test, and docs work
• use release Hex/GitHub sources when running mix deps.get, mix hex.build, or mix hex.publish so mix.lock stays publishable
• otherwise use Hex pristine ~> 0.2.1 plus GitHub subdir: dependencies for pristine_codegen and pristine_provider_testkit

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:

• raw bearer tokens such as fine-grained PATs, classic PATs, installation tokens, or OAuth access tokens
• OAuth-backed token sources through oauth2: [...]
• request-scoped basic auth for /applications/{client_id}/token* endpoints
• GitHub App JWT and installation-token flows through GitHubEx.AppAuth, which returns Pristine.Client runtime clients ready for generated operations

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

Ownership split:

• pristine owns the generic runtime OAuth and token-source mechanics
• GitHubEx.OAuth and GitHubEx.AppAuth own GitHub-specific auth semantics
• durable app installs, secret storage, and hosted callback orchestration stay outside the SDK

Docs Map

• Getting Started: installation, auth preflight, clients, and first calls
• Client Configuration: runtime options, request overrides, and typed responses
• Authentication and OAuth: bundled-example path, classic vs fine-grained PATs, OAuth apps, and application-token endpoints
• Auth Capability Matrix: generated per-operation token support and permission lookup
• GitHub App Authentication: JWTs, installation tokens, app user tokens, narrowing, and 403 debugging
• Pagination and Rate Limits: Link headers, wrapped responses, and retry behavior
• Common Workflows: repos, issues, pulls, workflow runs, and common read paths
• Architecture and Design Reference: the canonical end-to-end design, build, auth, and runtime reference for this repo
• Low-Level Requests: the raw request escape hatch on GitHubEx.Client.request/2
• Regeneration and Maintenance: pinned inputs, auth snapshot refresh, and codegen artifacts

Examples Map

• Examples README: example-by-example auth requirements, env vars, and runner commands
• examples/run_all.sh: run smoke, repos, oauth, app, or all

Pinned Upstream Contract

This repo is currently pinned to:

• GitHub REST API version header: 2026-03-10
• OpenAPI source: github/rest-api-description
• OpenAPI file: priv/upstream/openapi/api.github.com.2026-03-10.json
• Auth snapshot directory: priv/upstream/github_docs_auth/

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:

• priv/generated/provider_ir.json
• priv/generated/generation_manifest.json
• priv/generated/docs_inventory.json
• priv/generated/operation_auth_policies.json
• priv/generated/auth_manifest.json

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