@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

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:

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

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:

Single-tenant:

Multi-tenant (omit installationId):

The adapter automatically extracts installation IDs from webhooks and caches API clients per-installation.

Installation lookup

You can resolve the GitHub App installation ID associated with a Thread or Message:

• Single-tenant GitHub App mode returns the fixed configured installation ID.
• PAT mode returns undefined.
• Multi-tenant mode only succeeds after the adapter has received a webhook for that repository and cached the installation mapping. Use a persistent state adapter so the mapping survives restarts.

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

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