@chat-adapter/github weekly downloads statistics

@chat-adapter/github

npm package: @chat-adapter/github

GitHub adapter for Chat SDK. Respond to @mentions in PR and issue comment threads.

The GitHub adapter treats issue and pull request comments as messages, and issues/PRs as threads.

Documentation: chat-sdk.dev/adapters/official/github · Guides: vercel.com/kb/chat-sdk

Installation

pnpm add @chat-adapter/github

Scaffold with the CLI

To scaffold a new GitHub bot with this adapter preselected:

npx create-chat-sdk@latest my-bot --adapter github memory

Visit the adapters directory to see other available official and vendor-official adapters.

Quick start

For managed credentials and webhook verification, see Vercel Connect.

The adapter auto-detects credentials from GITHUB_TOKEN (or GITHUB_APP_ID/GITHUB_PRIVATE_KEY), GITHUB_WEBHOOK_SECRET, and GITHUB_BOT_USERNAME environment variables:

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

All options are auto-detected from environment variables when not provided.

Option	Required	Description
token	No*	Personal Access Token. Auto-detected from GITHUB_TOKEN
appId	No*	GitHub App ID. Auto-detected from GITHUB_APP_ID
privateKey	No	GitHub App private key (PEM). Auto-detected from GITHUB_PRIVATE_KEY
installationId	No	Installation ID (omit for multi-tenant). Auto-detected from GITHUB_INSTALLATION_ID
installationToken	No*	Vercel Connect mode: installation access token, or a () => string | Promise<string> resolver invoked per API call. Skips the App JWT exchange.
webhookSecret	No**	Webhook secret. Auto-detected from GITHUB_WEBHOOK_SECRET
webhookVerifier	No**	Custom verifier (request, body) => unknown | Promise<unknown> used in place of webhookSecret. Takes precedence over webhookSecret/GITHUB_WEBHOOK_SECRET. Required in Connect mode
userName	No	Bot username for @mention detection. Auto-detected from GITHUB_BOT_USERNAME (default: "github-bot")
botUserId	No	Bot's numeric user ID (auto-detected if not provided)
apiUrl	No	Override the GitHub API base URL (e.g. for GitHub Enterprise Server). Auto-detected from GITHUB_API_URL
logger	No	Logger instance (defaults to ConsoleLogger("info"))

*One of token/GITHUB_TOKEN, appId+privateKey/GITHUB_APP_ID+GITHUB_PRIVATE_KEY, or installationToken (Vercel Connect) is required.

**Either webhookSecret (via config or GITHUB_WEBHOOK_SECRET) or a webhookVerifier is required. When webhookVerifier is set it takes precedence and the secret is ignored.

Authentication

Option A — Vercel Connect

Use Vercel Connect to source installation access tokens at runtime instead of storing a GitHub App private key. The installationToken resolver supplies the token the adapter sends directly (skipping the App JWT exchange), and webhookVerifier verifies Connect trigger-forwarded webhooks via a Vercel OIDC token instead of a webhook secret.

The simplest path is the connectGitHubAdapter() helper from @vercel/connect/chat:

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

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

Or wire the fields yourself:

import { getToken } from "@vercel/connect";

createGitHubAdapter({
  installationToken: () =>
    getToken("github/acme-github", { subject: { type: "app" } }),
  webhookVerifier: myConnectWebhookVerifier,
  userName: "my-bot[bot]",
});

installationToken accepts a string or () => string | Promise<string> resolver invoked per API call, so it composes with Connect's short-lived tokens. When webhookVerifier is set it takes precedence over webhookSecret and GITHUB_WEBHOOK_SECRET.

Freshness: OIDC verification replaces GitHub's signature check, so request freshness relies on the short-lived OIDC token's expiry rather than a signed timestamp, and there is no built-in nonce/delivery-id de-duplication. Keep your webhook handlers idempotent (GitHub may also redeliver events).…