@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.

Installation

pnpm add @chat-adapter/github

Usage

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

Authentication

Option A: Personal Access Token

Best for personal projects, testing, or 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

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

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. Set Webhook URL to https://your-domain.com/api/webhooks/github
3. Generate and set a Webhook secret
4. Set permissions:
   • Repository > Issues: Read & write
   • Repository > Pull requests: Read & write
   • Repository > Metadata: Read-only
5. Subscribe to events: Issue comment, Pull request review comment
6. Click Create GitHub App
7. Note the App ID and click Generate a private key

2. Install the app:

1. Go to your app's settings then Install App
2. Click Install and choose repositories
3. Note the Installation ID from the URL:
   https://github.com/settings/installations/12345678                                           ^^^^^^^^

Single-tenant:

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.

Webhook setup

For repository or organization webhooks:

1. Go to repository/org 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 (required — the default application/x-www-form-urlencoded does not work)
4. Set Secret to match your webhookSecret
5. Select events: Issue comments, Pull request review comments

Warning: GitHub App webhooks are configured during app creation. Make sure to select application/json as the content type.

Thread model

GitHub has two types of comment threads:

Reactions

Supports GitHub's reaction emoji:

Configuration

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

*Either token/GITHUB_TOKEN or appId+privateKey/GITHUB_APP_ID+GITHUB_PRIVATE_KEY is required.

**webhookSecret is required — either via config or GITHUB_WEBHOOK_SECRET env var.

Environment variables

# Personal Access Token authGITHUB_TOKEN=ghp_xxxxxxxxxxxx# OR GitHub App authGITHUB_APP_ID=123456GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."GITHUB_INSTALLATION_ID=12345678  # Optional for multi-tenant# RequiredGITHUB_WEBHOOK_SECRET=your-webhook-secret

Features

Messaging

Rich content

Conversations

Message history

Platform-specific

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 modified before verification

"Invalid JSON" error

• Change webhook Content type to application/json

Bot not responding to mentions

• Verify webhook events are configured (issue_comment, pull_request_review_comment)
• Check the webhook URL is correct and accessible
• Ensure 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
• Use 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