GitHub

Install

Quick start

import { Chat } from "chat";
import { createGitHubAdapter } from "@chat-adapter/github";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    github: createGitHubAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from GitHub!");
});

Configuration

Either token or appId+privateKey is required, plus webhookSecret.

Authentication

Option A — Personal Access Token

Best for personal projects, testing, or single-repo bots.

1. Go to Settings then Developer settings then Personal access tokens.
2. Create a token with repo scope.
3. Set GITHUB_TOKEN.

createGitHubAdapter({
  token: process.env.GITHUB_TOKEN!,
});

Option B — GitHub App (recommended)

Better rate limits, security, and supports multiple installations.

Create the app:

1. Go to Settings then Developer settings then GitHub Apps then New GitHub App.
2. Set Webhook URL to https://your-domain.com/api/webhooks/github.
3. Set a Webhook secret.
4. Permissions: Issues — Read & write, Pull requests — Read & write, Metadata — Read-only.
5. Subscribe to events: Issue comment, Pull request review comment.
6. Click Create GitHub App and generate a private key.

Install the app:

1. From your app's settings click Install App and choose repositories.
2. Note the Installation ID in the URL: https://github.com/settings/installations/12345678.

Single-tenant config:

createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
  installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!, 10),
});

Multi-tenant (omit installationId):

createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
});

The adapter automatically extracts installation IDs from webhooks and caches API clients per-installation.

Advanced

Installation lookup

Resolve the GitHub App installation ID associated with a Thread or Message:

bot.onNewMention(async (thread, message) => {
  const installationIdFromThread = await github.getInstallationId(thread);
  const installationIdFromMessage = await github.getInstallationId(
    message.threadId
  );
});

• PAT mode — returns undefined.
• Single-tenant GitHub App — returns the configured installation ID.
• Multi-tenant — only succeeds after the adapter has received a webhook for that repository and cached the mapping. Use a persistent state adapter so the mapping survives restarts.

Direct API client

Access the underlying Octokit instance via .octokit:

const github = bot.getAdapter("github").octokit;
const { data: pulls } = await github.rest.pulls.list({
  owner: "vercel",
  repo: "chat",
  state: "open",
});

PAT and single-tenant App modes return the same client anywhere. Multi-tenant mode requires webhook-handler context — calling .octokit outside a handler throws.

The previous .client getter still works as a deprecated alias for .octokit.

Webhook setup

For repository or organization webhooks:

1. Settings then Webhooks then Add webhook.
2. Set payload URL to https://your-domain.com/api/webhooks/github.
3. Set Content type to application/json (the default application/x-www-form-urlencoded does not work).
4. Set Secret to match webhookSecret.
5. Select events: Issue comments, Pull request review comments.

GitHub App webhooks are configured during app creation — make sure to select application/json.

Thread model

Reactions

Feature support