GitHub

ChatBotKit's GitHub integration puts an AI agent inside your issues and pull requests. @mention the bot in any issue or pull request comment and it replies in the thread, using its configured model, backstory, skillsets, datasets, and memory.

Each integration is its own GitHub App. After it is installed on the repositories you choose, the agent works on its own: GitHub forwards events to ChatBotKit, the bot answers when it is summoned, and everything it does is scoped to the repositories and permissions the App was granted.

How the Connection Works

Unlike a single shared app, this integration uses your own GitHub App, identified per integration. There are three pieces of configuration:

• App ID and Private Key - your GitHub App's identity. ChatBotKit signs a short-lived App token with these to mint installation access tokens on demand. Nothing long-lived is stored.
• Webhook Secret - used to verify that inbound webhook deliveries genuinely come from GitHub (x-hub-signature-256).

The installation id is never stored - it arrives in every webhook event and is used, together with your App credentials, to mint a token to reply. This is why one App can serve many organizations at once.

Step-by-Step Installation Guide

The setup is a small chicken-and-egg: the GitHub App's webhook URL contains the ChatBotKit integration's id, so you create the integration first, then the App, then paste the App's credentials back.

Phase 1: Create Your GitHub Integration

1. Navigate to Integrations in your ChatBotKit dashboard.

2. Click the GitHub Bot button to start the setup process.

3. Configure the basics:

   • Name: A clear, memorable name for this integration.
   • Bot: Select the bot that should answer. Its backstory, model, datasets, and skillsets drive the replies.

4. Click "Create".

5. Open the Webhook section and copy the Webhook Payload URL. It looks like:

   You will paste this into the GitHub App in the next phase.

Phase 2: Register a GitHub App

1. On GitHub, go to Settings → Developer settings → GitHub Apps → New GitHub App (for an organization, use the org's Developer settings).
2. Set a GitHub App name and a Homepage URL (your site is fine).
3. Under Webhook:
   • Tick Active.
   • Webhook URL: paste the Webhook Payload URL from Phase 1.
   • Webhook secret: enter a strong secret you generate. Keep it - you will paste it into ChatBotKit too.
4. Under Repository permissions, grant:
   • Issues: Read & write - comment, label, assign, open/close.
   • Pull requests: Read & write - comment on pull requests and read diffs.
   • Contents: Read-only - read and list files. Use Read & write only if you intend to use the token ability for git/CLI write workflows.
   • Metadata: Read-only (this is mandatory and selected by default).
5. Under Subscribe to events, select:
   • Issue comment
   • Pull request review comment
6. Choose where the App can be installed (your account only, or any account), then click Create GitHub App.
7. On the App's page, note the App ID.
8. Scroll to Private keys and click Generate a private key. A .pem file downloads - you will paste its contents into ChatBotKit.

Phase 3: Connect Credentials in ChatBotKit

1. Return to your GitHub integration in ChatBotKit.
2. In the GitHub Application Configuration section, fill in:
   • App ID: the numeric App ID from Phase 2.
   • Private Key: paste the full contents of the downloaded .pem file (including the -----BEGIN… and -----END… lines).
   • Webhook Secret: the same secret you set on the GitHub App.
3. Click "Save".

Phase 4: Install the App on Your Repositories

1. On the GitHub App's page, open Install App and choose the account/organization.
2. Select All repositories or Only select repositories and pick the repos the bot may access. GitHub enforces this scope - the bot can only act on repositories where the App is installed.
3. Confirm the installation.

Phase 5: Summon the Bot

Open an issue or pull request in an installed repository and @mention the bot by its GitHub App name, for example:

The bot reacts with 👀 to acknowledge, then replies in the thread.

Using the Bot

• @mention to summon: The bot only acts when it is explicitly @mentioned - including in a thread it has already replied to. This keeps it out of ordinary discussion between people.
• Context: On first contact in a thread the bot reads the issue body, recent comments, and - on a pull request - the diff, so its reply is grounded in the actual conversation and code.
• Continuity: The conversation persists per issue/PR thread, so follow-up @mentions continue the same conversation.

Skillset Abilities

Give the bot a skillset that includes the GitHub abilities to let it act on the repository:

• Post GitHub Comment - reply in an issue or pull request.
• Label GitHub Issue - add labels.
• Assign GitHub Issue - assign people.
• Open or Close GitHub Issue - change issue/PR state.
• Read GitHub File - read a file's contents at a path.
• List GitHub Files - list files and directories.
• Call GitHub API - make an authenticated call to any GitHub REST endpoint (advanced; bounded by the App's permissions).
• Create GitHub Repository Token - mint a short-lived, repository-scoped access token for CLI and git workflows.

Every ability acts through a token minted from this integration's own GitHub App credentials, so it can never exceed the permissions you granted the App or the repositories you installed it on.

Caveats

When the bot is @mentioned, the inbound event is handled immediately by the agent - but that immediate, in-line processing has a time limit. There is a bound on how long a single synchronous response can run, so it is not the place for heavy, long-running work.

This means the agent should decide, up front, how to handle each request:

• Respond immediately - for quick answers, triage, and short actions that comfortably finish within the limit.
• Schedule a long-running task - for work that needs more time. Tasks run independently of the inbound event and can run for much longer - hours, or even days - to completion.

In practice, the agent acknowledges the request in the thread, hands the heavy work off to a task, and reports back as it makes progress. Give the bot a skillset with task abilities so it can make this decision and offload long jobs rather than blocking on the initial event.

Troubleshooting

• The bot does not respond: Confirm the App is installed on that repository, you subscribed to Issue comment and Pull request review comment, and you actually @mentioned the App's name. Check the integration's Events section for delivery errors.
• Signature verification errors: The Webhook Secret in ChatBotKit must match the one set on the GitHub App exactly.
• "Missing App credentials": Ensure the App ID and Private Key are filled in and the private key includes the full PEM, including the header and footer lines.
• Permission errors when acting: Grant the corresponding Repository permission on the App (e.g. Issues: Read & write to comment or label), then reinstall or accept the updated permissions on the installation.

Security Notes

Treat the Private Key and Webhook Secret as sensitive credentials. If either is compromised, rotate it in the GitHub App settings and update the integration. Because the integration mints short-lived, repository-scoped tokens on demand, there is no long-lived access token to leak - and the App's granted permissions plus its installed repositories are the hard ceiling on what the agent can do.