GitHub

Create a new bot

Scaffold a Next.js bot with the GitHub adapter using create-chat-sdk:

The generated app uses the Memory state adapter for local development. To add the adapter to an existing app, start at Install.

Install

Quick start

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

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

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

The memory state adapter keeps subscriptions and locks in process memory, which suits local development. Use Redis or PostgreSQL in production.

Then create the webhook route:

import { after } from "next/server";
import { bot } from "@/lib/bot";

export async function POST(request: Request): Promise<Response> {
  return bot.webhooks.github(request, {
    waitUntil: (task) => after(() => task),
  });
}

Authentication

Vercel Connect

Use Vercel Connect to source installation access tokens at runtime instead of storing a GitHub App private key. The connectGitHubAdapter() helper from @vercel/connect/chat wires an installationToken resolver, which skips the App JWT exchange, and a webhookVerifier for Connect trigger-forwarded webhooks:

import { createGitHubAdapter } from "@chat-adapter/github";
import { connectGitHubAdapter } from "@vercel/connect/chat";

createGitHubAdapter({
  ...connectGitHubAdapter("github/acme-github"),
  userName: "my-bot[bot]",
});

installationToken accepts a string or () => string | Promise<string> resolver invoked per API call. When webhookVerifier is set it takes precedence over webhookSecret and GITHUB_WEBHOOK_SECRET.

createGitHubAdapter({
  ...connectGitHubAdapter("github/acme-github"),
  botUserId: 12345678,
});

Create the connector and attach it to your project with the Vercel CLI. --trigger-path registers the GitHub webhook route as the trigger destination, and vercel env pull downloads a development OIDC token for local runs:

vercel link
vercel connect create github --name acme-github --triggers
vercel connect attach github/acme-github --triggers --trigger-path /api/webhooks/github
vercel env pull

Without --trigger-branch, Connect forwards webhooks to your production deployment. See Vercel Connect for the full setup.

GitHub App

We recommend a GitHub App. It has better rate limits and security than a personal access token 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. Under permissions, set Issues and Pull requests to Read & write, and Metadata to 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 configuration

Set installationId to accept comments only from that GitHub App installation. After verification, a new comment (issue_comment or pull_request_review_comment with action created) from a different installation gets a 404, handlers don't run, and the adapter logs a warning with both IDs. The check runs whether you verify with webhookSecret or a custom webhookVerifier, and other event types and actions aren't checked.

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

Multi-tenant configuration

Omit installationId:

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

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

Personal access token

A personal access token suits personal projects, testing, and 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!,
});

Configuration

One of token, appId+privateKey, or installationToken (Vercel Connect) is required, plus either webhookSecret or a webhookVerifier.

Environment variables

Webhooks

For repository or organization webhooks:

1. Open Settings then Webhooks then Add webhook.
2. Set the 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.

You configure GitHub App webhooks when you create the app. Make sure to select application/json there too.

Reactions

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
  );
});

The result depends on the auth mode:

• With a personal access token, it returns undefined.
• With a single-tenant GitHub App, it returns the configured installation ID.
• With a multi-tenant GitHub App, it succeeds only 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 through .octokit:

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

Personal access token and single-tenant App modes return the same client anywhere. Multi-tenant mode requires webhook handler context, and calling .octokit outside a handler throws.

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

Thread IDs

Issues and pull requests map to threads, and comments map to messages:

Feature support

Resources

• Ship a GitHub code review bot with Hono and Redis: build a GitHub bot that reviews pull requests on demand. When a user @mentions the bot on a PR, Chat SDK picks up the mention, spins up a Vercel Sandbox with the repo cloned, and uses AI SDK to analyze the diff.

See all guides and templates on the resources page.