vercel__chat/packages/adapter-github

@chat-adapter/github

GitHub adapter for the chat SDK. Enables bots to respond to @mentions in GitHub PR comment threads.

Installation

npm install chat @chat-adapter/github

Usage

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

const chat = new Chat({
  userName: "my-bot",
  adapters: {
    github: createGitHubAdapter({
      token: process.env.GITHUB_TOKEN!,
      webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
      userName: "my-bot",
      logger: console,
    }),
  },
  state: new MemoryState(),
  logger: "info",
});

// Handle @mentions in PR comments
chat.onNewMention(async (thread, message) => {
  await thread.post("Hello from GitHub!");
});

Configuration

Option	Required	Description
token	Yes*	Personal Access Token with repo scope
appId	Yes*	GitHub App ID
privateKey	For Apps	GitHub App private key (PEM format)
installationId	No	Installation ID (omit for multi-tenant)
webhookSecret	Yes	Webhook secret for signature verification
userName	Yes	Bot username for @mention detection
botUserId	No	Bot's numeric user ID (auto-detected if not provided)

*Either token or appId/privateKey is required.

Environment Variables

# 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 apps

# Webhook secret (required)
GITHUB_WEBHOOK_SECRET=your-webhook-secret

GitHub Setup

Option A: Personal Access Token (PAT)

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

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

Option B: GitHub App (Recommended)

Better rate limits, security, and supports multiple installations.

1. Create the App

1. Go to Settings → Developer settings → GitHub Apps → New GitHub App
2. Fill in:
   • Name: Your bot's name
   • Homepage URL: Your app's website
   • Webhook URL: https://your-domain.com/api/webhooks/github
   • Webhook secret: Generate a secure secret
3. Set Permissions:
   • Repository -> Issues: Read & write
   • Repository -> Pull requests: Read & write
   • Repository -> Metadata: Read-only
4. Subscribe to events:
   • Issue comment
   • Pull request review comment
5. Create the app and generate a private key

2. Install the App

1. Install the app on your organization or repositories
2. Note the Installation ID from the URL (e.g., https://github.com/settings/installations/12345678)

3. Configure the Adapter

Single-tenant (fixed installation):

createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
  installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
  userName: "my-bot[bot]",
  logger: console,
});

Multi-tenant (public app anyone can install):

Simply omit installationId. The adapter automatically extracts it from webhooks and caches API clients per-installation:

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

const chat = new Chat({
  userName: "my-bot[bot]",
  adapters: {
    github: createGitHubAdapter({
      appId: process.env.GITHUB_APP_ID!,
      privateKey: process.env.GITHUB_PRIVATE_KEY!,
      // No installationId - handled automatically!
      webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
      userName: "my-bot[bot]",
      logger: console,
    }),
  },
  // Use Redis to persist installation mappings
  state: new RedisState({ url: process.env.REDIS_URL! }),
  logger: "info",
});

Webhook Setup

See the GitHub Webhooks documentation for detailed instructions.

For repository/org webhooks:

1. Go to repository/org Settings → Webhooks → Add webhook
2. Set Payload URL to https://your-domain.com/api/webhooks/github
3. Set Content type to application/json (required - the default application/x-www-form-urlencoded will not work)
4. Set Secret to match your webhookSecret
5. Select events:
   • Issue comments (PR-level)
   • Pull request review comments (line-specific)

For GitHub Apps: Webhooks are configured during app creation. Make sure to select application/json as the content type.

Features

• Message posting and editing
• Message deletion
• Reaction handling (add/remove)
• PR-level comments (Conversation tab)
• Review comment threads (Files Changed tab - line-specific)
• Cards (rendered as GitHub Flavored Markdown)
• Multi-tenant support (automatic installation ID handling)

Thread Model

GitHub has two types of comment threads:

Type	Tab	API	Thread ID Format
PR-level	Conversation	Issue Comments	github:{owner}/{repo}:{prNumber}
Review comments	Files Changed	PR Review Comments	github:{owner}/{repo}:{prNumber}:rc:{commentId}

Example thread IDs:

• github:acme/app:123 (PR-level)
• github:acme/app:123:rc:456789 (line-specific review comment)

Reactions

Supports GitHub's reaction emoji:

SDK Emoji	GitHub Reaction
thumbs_up	👍 (+1)
thumbs_down	👎 (-1)
laugh	😄
confused	😕
heart	❤️
hooray	🎉
rocket	🚀
eyes	👀

Limitations

• No typing indicators - GitHub doesn't support typing indicators
• No streaming - Messages posted in full (editing supported for updates)
• No DMs - GitHub doesn't have direct messages
• No modals - GitHub doesn't support interactive modals
• Action buttons - Rendered as text; use link buttons for clickable actions

Troubleshooting

"Invalid signature" error

• Verify GITHUB_WEBHOOK_SECRET matches your webhook configuration
• Ensure the request body isn't being modified before verification

"Invalid JSON" error

• Change webhook Content type to application/json (GitHub defaults to application/x-www-form-urlencoded which doesn't work)

Bot not responding to mentions

• Verify webhook events are configured (issue_comment, pull_request_review_comment)
• Check that the webhook URL is correct and accessible
• Ensure the bot has been installed on the repository
• Verify the userName config matches your bot's GitHub username

"Installation ID required" error

• This occurs when making API calls outside webhook context in multi-tenant mode
• Ensure you're using a persistent state adapter (Redis) to store installation mappings
• The first interaction must come from a webhook to establish the mapping

Rate limiting

• PATs have lower rate limits than GitHub Apps
• Consider switching to a GitHub App for production use

License

MIT