Announcing the Distilled GitHub SDK

Automate repositories, issues, pull requests, releases, and Actions with an Effect-native SDK generated from GitHub's official OpenAPI description.

GitHub automation lives on the critical path of modern delivery: repository policy, issues, pull requests, checks, releases, deployments, and security operations. @kevinmichaelchen/distilled-github brings that REST surface into Effect with runtime validation and explicit failure behavior.

GitHub, at a glance

GitHub hosts source code and the collaboration and automation systems around it. Its REST API supports integrations that retrieve data and automate workflows, and GitHub publishes the complete contract in the official github/rest-api-description repository.

Official REST docs

Authentication, versioning, rate limits, best practices, and endpoint references.

Official OpenAPI

GitHub’s versioned, machine-readable REST description.

SDK repository

GitHub policy plus 1,167 committed generated operations.

Specification mirror

The exact bundled description used for generation.

Why Effect and Distilled?

GitHub workflows combine network calls with branching policy: look up repository state, create or update an issue, wait on checks, respect primary and secondary rate limits, and surface useful diagnostics. Effect makes dependencies, concurrency, retries, timeouts, cancellation, and tracing composable. Distilled adds decoded GitHub error envelopes, version headers, secret redaction, runtime schemas, and categorized retries.

Because generated operations are committed, a GitHub API update produces a reviewable source diff. You can see which request or response types changed before releasing the next package.

How we made the SDK

Use GitHub's own contract

The source mirror extracts an exact versioned bundle from github/rest-api-description rather than inventing a smaller community schema.

Keep source history bounded

The compact mirror avoids dragging a large upstream repository and its history into every consumer SDK checkout.

Generate through the shared factory

The Alchemy-derived OpenAPI generator emits runtime schemas and yieldable Effect operations; GitHub-specific auth, errors, and retry policy stay handwritten.

Release by workload identity

The private repository publishes through its dedicated GitHub Actions workflow and npm OIDC trust.

Code Examples

Set GITHUB_TOKEN, then install:

npm install @kevinmichaelchen/distilled-github effect

pnpm add @kevinmichaelchen/distilled-github effect

bun add @kevinmichaelchen/distilled-github effect

import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
import {
  CredentialsFromEnv,
  issuesListForRepo,
  pullsCreate,
  reposGet,
} from "@kevinmichaelchen/distilled-github";

const GitHubLive = Layer.mergeAll(FetchHttpClient.layer, CredentialsFromEnv);

Inspect a repository

Read repository metadata before deciding whether a workflow should inspect issues, create branches, or trigger another automation.

const inspectRepository = reposGet({
  owner: "acme",
  repo: "payments",
}).pipe(Effect.provide(GitHubLive));

List open issues

Build triage queues from open issues filtered by labels and ordered by recent activity.

const listOpenIssues = issuesListForRepo({
  owner: "acme",
  repo: "payments",
  state: "open",
  labels: "bug,triage",
  sort: "updated",
  direction: "desc",
  per_page: 50,
}).pipe(Effect.provide(GitHubLive));

Open a pull request

Turn a prepared branch into a reviewable pull request from a release bot or repository automation.

const openPullRequest = pullsCreate({
  owner: "acme",
  repo: "payments",
  title: "Reduce checkout latency",
  head: "automation/checkout-cache",
  base: "main",
  body: "Adds a bounded cache around the pricing lookup.",
  draft: true,
}).pipe(Effect.provide(GitHubLive));

GITHUB_API_URL supports GitHub Enterprise Server, while GITHUB_API_VERSION controls the explicit REST version header.

Available now

Browse the GitHub SDK guide, inspect the implementation, or install @kevinmichaelchen/distilled-github.