03 // GitHub

The GitHub app runtime

The GitHub fragment handles app auth, webhook ingestion, installation sync, and repository actions so you can build product logic on top.

Install

npm install @fragno-dev/github-app-fragment @fragno-dev/db

npm install @fragno-dev/github-app-fragment @fragno-dev/db

Own the sync

Installations + repos

Best for

Repo-aware products

Capabilities

App auth handled

JWT and installation token flows are built in, so you can focus on product logic.

Webhook-driven sync

Track installations and repositories from GitHub events instead of manual polling.

Repo linking built-in

Your users stay in control of what they share with your product.

Interface

Typed routes cover the core primitives: installations, linked repositories, sync actions, and pull-request operations.

Route surface

POST /webhooks
GET  /installations
GET  /installations/:installationId/repos
POST /installations/:installationId/sync
GET  /repositories/linked
POST /repositories/link
POST /repositories/unlink
GET  /repositories/:owner/:repo/pulls
POST /repositories/:owner/:repo/pulls/:number/reviews

POST /webhooksGET  /installationsGET  /installations/:installationId/reposPOST /installations/:installationId/syncGET  /repositories/linkedPOST /repositories/linkPOST /repositories/unlinkGET  /repositories/:owner/:repo/pullsPOST /repositories/:owner/:repo/pulls/:number/reviews

Why it matters

If your product touches source code, reviews, CI, or developer onboarding, GitHub is core infrastructure. This fragment gives you a stable baseline without requiring deep expertise in GitHub App auth and webhook orchestration first.

Blueprint

Add the app once, then layer product logic on top.

Create the server

import {
  createGitHubAppFragment,
  type GitHubAppFragmentConfig,
} from "@fragno-dev/github-app-fragment";

const config: GitHubAppFragmentConfig = {
  appId: process.env.GITHUB_APP_ID ?? "",
  appSlug: process.env.GITHUB_APP_SLUG ?? "",
  privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY ?? "",
  webhookSecret: process.env.GITHUB_APP_WEBHOOK_SECRET ?? "",
};

export const githubFragment = createGitHubAppFragment(config, {
  databaseAdapter,
  mountRoute: "/api/github",
});

import {  createGitHubAppFragment,  type GitHubAppFragmentConfig,} from "@fragno-dev/github-app-fragment";const config: GitHubAppFragmentConfig = {  appId: process.env.GITHUB_APP_ID ?? "",  appSlug: process.env.GITHUB_APP_SLUG ?? "",  privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY ?? "",  webhookSecret: process.env.GITHUB_APP_WEBHOOK_SECRET ?? "",};export const githubFragment = createGitHubAppFragment(config, {  databaseAdapter,  mountRoute: "/api/github",});

Create a client

import { createGitHubAppFragmentClient } from "@fragno-dev/github-app-fragment/react";

const github = createGitHubAppFragmentClient({ baseUrl: "/api/github" });

const syncInstallation = github.useSyncInstallation();

import { createGitHubAppFragmentClient } from "@fragno-dev/github-app-fragment/react";const github = createGitHubAppFragmentClient({ baseUrl: "/api/github" });const syncInstallation = github.useSyncInstallation();

Use it

await syncInstallation.mutate({
  path: { installationId: "12345" },
});

await fetch("/api/github/repositories/acme/docs/pulls/42/reviews", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ event: "COMMENT", body: "Looks good." }),
});

await syncInstallation.mutate({  path: { installationId: "12345" },});await fetch("/api/github/repositories/acme/docs/pulls/42/reviews", {  method: "POST",  headers: { "content-type": "application/json" },  body: JSON.stringify({ event: "COMMENT", body: "Looks good." }),});

Outcome

Ship GitHub-aware features without rebuilding the platform layer.

Webhook ingestion

const githubFragment = createGitHubAppFragment(
  {
    appId: process.env.GITHUB_APP_ID ?? "",
    appSlug: process.env.GITHUB_APP_SLUG ?? "",
    privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY ?? "",
    webhookSecret: process.env.GITHUB_APP_WEBHOOK_SECRET ?? "",
    webhook: (register) => {
      register("installation.deleted", async (event, idempotencyKey) => {
        const installationId = event.payload.installation?.id;
        if (!installationId) return;
        await revokeWorkspaceGitHubAccess(installationId, idempotencyKey);
      });

      register(["installation_repositories.added", "installation_repositories.removed"], async (event) => {
        await updateProjectRepositoryAccess({
          installationId: event.payload.installation.id,
          eventName: event.name,
        });
      });
    },
  },
  { databaseAdapter, mountRoute: "/api/github" },
);

const githubFragment = createGitHubAppFragment(  {    appId: process.env.GITHUB_APP_ID ?? "",    appSlug: process.env.GITHUB_APP_SLUG ?? "",    privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY ?? "",    webhookSecret: process.env.GITHUB_APP_WEBHOOK_SECRET ?? "",    webhook: (register) => {      register("installation.deleted", async (event, idempotencyKey) => {        const installationId = event.payload.installation?.id;        if (!installationId) return;        await revokeWorkspaceGitHubAccess(installationId, idempotencyKey);      });      register(["installation_repositories.added", "installation_repositories.removed"], async (event) => {        await updateProjectRepositoryAccess({          installationId: event.payload.installation.id,          eventName: event.name,        });      });    },  },  { databaseAdapter, mountRoute: "/api/github" },);

Onboarding

Sync installations and available repos fast.

Automation

React to installs and repo changes from webhooks.

Reviews

Trigger pull-request actions from typed, product-owned routes.