GitHub

Configure the GitHub adapter to 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

Terminal

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:

lib/bot.ts

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.

Go to Settings > Developer settings > Personal access tokens
Create a new token with repo scope
Set GITHUB_TOKEN environment variable

lib/bot.ts

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

Option B: GitHub App (recommended)

Better rate limits, security, and supports multiple installations.

1. Create the app:

Go to Settings > Developer settings > GitHub Apps > New GitHub App
Set Webhook URL to https://your-domain.com/api/webhooks/github
Generate and set a Webhook secret
Set permissions:
- Repository > Issues: Read & write
- Repository > Pull requests: Read & write
- Repository > Metadata: Read-only
Subscribe to events: Issue comment, Pull request review comment
Click Create GitHub App
Note the App ID and click Generate a private key

2. Install the app:

Go to your app's settings then Install App
Click Install and choose repositories

Note the Installation ID from the URL:

https://github.com/settings/installations/12345678
                                           ^^^^^^^^

Single-tenant:

lib/bot.ts

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

Multi-tenant (omit installationId):

lib/bot.ts

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:

Go to repository/org Settings then Webhooks then Add webhook
Set Payload URL to https://your-domain.com/api/webhooks/github
Set Content type to application/json (required — the default application/x-www-form-urlencoded does not work)
Set Secret to match your webhookSecret
Select events: Issue comments, Pull request review comments

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:

Type	Tab	Thread ID format
PR-level	Conversation	`github:{owner}/{repo}:{prNumber}`
Review comments	Files Changed	`github:{owner}/{repo}:{prNumber}:rc:{commentId}`

Reactions

Supports GitHub's reaction emoji:

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

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`
`webhookSecret`	No**	Webhook secret. Auto-detected from `GITHUB_WEBHOOK_SECRET`
`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)
`logger`	No	Logger instance (defaults to `ConsoleLogger("info")`)

*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

.env.local

# 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

Features

Feature	Supported
Mentions	Yes
Reactions (add/remove)	Yes
Cards	GFM Markdown
Modals	No
Streaming	No
DMs	No
File uploads	No
Typing indicator	No
Message history	Yes
Multi-tenant	Yes (GitHub App)

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

GitHub

On this page