package
GitHub adapter for Chat SDK — respond to @mentions in pull request and issue comment threads
npm install @chat-adapter/githubGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
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
pnpm add @chat-adapter/githubTo scaffold a new GitHub bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter github memoryVisit the adapters directory to see other available official and vendor-official adapters.
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!");
});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.
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).
Set
botUserIdfor self-message detection. In Connect mode the adapter only holds an installation token, so it can't auto-detect its own bot user id (the/applookup needs the App's JWT). Without it, the adapter can't tell its own comments apart from users' and will reply to itself in a loop. The adapter learns the id from the first comment it posts, but that lives in memory — on serverless (where each webhook may hit a fresh instance) that isn't enough. PassbotUserId(the numeric id of your…[bot]user) so every instance knows it up front:createGitHubAdapter({ ...connectGitHubAdapter("github/acme-github"), botUserId: 12345678, // id of your-app[bot] });Or set the
GITHUB_BOT_USER_IDenvironment variable, which the adapter auto-detects. Find the id (no auth needed) withcurl -s 'https://api.github.com/users/your-app%5Bbot%5D'.
Best for personal projects, testing, or single-repo bots.
repo scopeGITHUB_TOKEN environment variablecreateGitHubAdapter({
token: process.env.GITHUB_TOKEN!,
});Better rate limits, security, and supports multiple installations.
1. Create the app:
https://your-domain.com/api/webhooks/github2. Install the app:
https://github.com/settings/installations/12345678
^^^^^^^^Single-tenant:
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.
Deliveries without an installation object still reach handlers. GitHub omits it from repository and organization webhooks, so those keep working in this mode. Vercel Connect mode (installationToken) has no configured installation ID and skips this check.
createGitHubAdapter({
appId: process.env.GITHUB_APP_ID!,
privateKey: process.env.GITHUB_PRIVATE_KEY!,
installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
});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.
You can resolve the GitHub App installation ID associated with a Thread or Message:
import { Chat } from "chat";
import { createGitHubAdapter } from "@chat-adapter/github";
const github = createGitHubAdapter({
appId: process.env.GITHUB_APP_ID!,
privateKey: process.env.GITHUB_PRIVATE_KEY!,
webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
});
const bot = new Chat({
adapters: { github },
});
bot.onNewMention(async (thread, message) => {
const installationIdFromThread = await github.getInstallationId(thread);
const installationIdFromMessage = await github.getInstallationId(message.threadId);
await thread.post(
`Thread install: ${installationIdFromThread}, message install: ${installationIdFromMessage}`
);
});undefined.For anything beyond the unified SDK, 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 GitHub App modes (with a fixed installationId) return the same client anywhere. Multi-tenant mode requires webhook handler context to resolve the right installation — calling .octokit outside a handler throws.
The previous
.clientgetter still works as a deprecated alias for.octokit.
For repository or organization webhooks:
https://your-domain.com/api/webhooks/githubapplication/json (required — the default application/x-www-form-urlencoded does not work)webhookSecretWarning: GitHub App webhooks are configured during app creation. Make sure to select
application/jsonas the content type.
GitHub has three types of comment threads:
| Type | Context | Thread ID format |
|---|---|---|
| PR-level | PR Conversation tab | github:{owner}/{repo}:{prNumber} |
| Review comments | PR Files Changed tab | github:{owner}/{repo}:{prNumber}:rc:{commentId} |
| Issue comments | Issue thread | github:{owner}/{repo}:issue:{issueNumber} |
Supports GitHub's reaction emoji:
| SDK emoji | GitHub reaction |
|---|---|
thumbs_up | +1 |
thumbs_down | -1 |
laugh | laugh |
confused | confused |
heart | heart |
hooray | hooray |
rocket | rocket |
eyes | eyes |
# Personal Access Token auth
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# OR GitHub App auth
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
GITHUB_INSTALLATION_ID=12345678 # Optional for multi-tenant
# Required
GITHUB_WEBHOOK_SECRET=your-webhook-secret
# Optional: GitHub Enterprise Server
GITHUB_API_URL=https://github.example.com/api/v3| Feature | Supported |
|---|---|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| File uploads | No |
| Streaming | Buffered (accumulates then sends) |
| Feature | Supported |
|---|---|
| Card format | GFM Markdown |
| Buttons | No |
| Link buttons | No |
| Select menus | No |
| Tables | GFM |
| Fields | Yes |
| Images in cards | Yes |
| Modals | No |
| Feature | Supported |
|---|---|
| Slash commands | No |
| Mentions | Yes |
| Add reactions | Yes |
| Remove reactions | Partial |
| Typing indicator | No |
| DMs | No |
| Ephemeral messages | No |
| Feature | Supported |
|---|---|
| Fetch messages | Yes |
| Fetch single message | No |
| Fetch thread info | Yes |
| Fetch channel messages | Yes |
| List threads | Yes |
| Fetch channel info | Yes |
| Post channel message | No |
| Feature | Supported |
|---|---|
| Multi-tenant | Yes (GitHub App) |
GITHUB_WEBHOOK_SECRET matches your webhook configurationapplication/jsonuserName config matches your bot's GitHub usernameSee all guides and templates at chat-sdk.dev/resources.
If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chatThe skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit — it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 47 packages.
10.1 MB
Includes dependencies.
4 direct dependencies.
4.45.0
4.45.0
^22.0.1
22.0.1
^8.2.0
8.3.1
4.45.0
4.45.0