getting-started.md

Getting Started

GitHubEx is a generated, runtime-thin SDK for the GitHub REST API. It keeps the provider-local surface in GitHubEx.* while targeting the bounded pristine family boundary for runtime execution. Lower unary HTTP execution stays under pristine; github_ex does not expose raw lower transport packages as part of its public API.

Auth Preflight

Before you create credentials, choose your path:

• Bundled examples: use the exact fine-grained PAT recipe in Authentication and OAuth and the per-example table in Examples README.
• Broad local exploration: start with Auth Capability Matrix before you assume one token type covers the SDK surface you want.
• Installed automation: read GitHub App Authentication.

Install

def deps do
  [
    {:github_ex, "~> 0.1.1"}
  ]
end

mix deps.get

For local multi-repo development, a sibling checkout is also a supported installation shape:

def deps do
  [
    {:github_ex, path: "../github_ex"}
  ]
end

Inside this repo, pristine dependencies follow the same policy:

• prefer sibling-relative paths when those checkouts exist for normal compile, test, docs, and mix deps.get
• use the published dependency surface when running mix hex.build or mix hex.publish
• set GITHUB_EX_HEX_DEPS=1 if you want mix deps.get to ignore sibling ../pristine checkouts and resolve the published dependency surface instead
• otherwise use Hex pristine ~> 0.2.1 plus GitHub subdir: dependencies for pristine_codegen and pristine_provider_testkit

That keeps local development and downstream consumption aligned without a vendored deps/ layout.

Create a Client

With a bearer token:

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

Without auth for public endpoints:

client = GitHubEx.Client.new()

Defaults:

• base_url: https://api.github.com
• accept: application/vnd.github+json
• X-GitHub-Api-Version: 2026-03-10
• timeout_ms: 60000

First Calls

Authenticated user:

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

Repository issues:

{:ok, issues} =
  GitHubEx.Issues.list_for_repo(client, %{
    "owner" => "octocat",
    "repo" => "Hello-World",
    "state" => "open"
  })

Pull requests:

{:ok, pulls} =
  GitHubEx.Pulls.list(client, %{
    "owner" => "octocat",
    "repo" => "Hello-World"
  })

Wrapped Responses

Normal generated calls return decoded JSON-shaped maps and lists. When you need GitHub-specific response metadata such as pagination links or rate-limit headers, ask for a wrapped response:

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

response.data
response.rate_limit
response.links

For generated list endpoints, prefer the helper in Pagination and Rate Limits.