←back to manuals

GitHub Integration

Integrate ChatBotKit with GitHub to deploy intelligent AI agents directly inside issues and pull requests. @mention the bot to summon it and let it reply in-thread.

ChatBotKit's GitHub integration lets you summon an AI agent from any issue or pull request by @mentioning it. The agent replies in-thread as a comment.

Creating a GitHub Integration

To create a new GitHub integration, send a POST request with your configuration:

How it authenticates

Each integration is its own GitHub App. Store the App's appId and privateKey on the integration, and point the App's webhook at this integration's event URL (below). The webhookSecret validates the x-hub-signature-256 header. The installation id is not stored - it arrives in every event payload and is combined with the App key to mint a short-lived token to reply.

Webhook Configuration

Set the GitHub App webhook URL to this integration's event endpoint:

Subscribe to these events: issue_comment, pull_request_review_comment. Then install the App on the target org(s) and pick the repositories it may access - GitHub enforces that scope, so the bot answers wherever it is installed and @mentioned.

Warning: The webhook secret is a sensitive credential. Never commit it to version control. If compromised, rotate it in GitHub and update your ChatBotKit integration immediately.

Validating GitHub Integration Credentials

Before your GitHub integration can function, you must validate that the GitHub App credentials are correctly configured. The setup endpoint probes your integration by testing the App ID and private key against GitHub's API. This serves as a health check to ensure your authentication configuration is valid and your GitHub App has proper access permissions.

This validation step is critical because GitHub App authentication requires precise configuration. The App ID, private key, and installation permissions must all be correctly set up. By running setup, you'll immediately discover any misconfiguration rather than encountering failures later during actual bot operations.

To validate your GitHub integration credentials, send a POST request to the setup endpoint with the integration ID:

The endpoint will probe your GitHub App configuration by attempting to list your App's installations. A successful response confirms that:

  • Your GitHub App ID is correctly configured
  • Your GitHub App private key is valid and properly formatted
  • Your App has permission to list installations
  • Your GitHub account has proper authorization

Response on Success:

The installations field indicates how many GitHub installations your App currently has access to. This represents the repositories and organizations where your App is installed.

Common Validation Errors:

  • Invalid App ID or Private Key: Double-check that you've copied the App ID and private key exactly from your GitHub App settings, including all special characters
  • Expired Private Key: GitHub App private keys have limited validity. Regenerate a new private key in your GitHub App settings if needed
  • Missing Permissions: Ensure your App has the necessary permissions for bot operations (typically read access to repositories, and access to pull requests/issues if needed)
  • Installation Not Found: Verify that your GitHub App is actually installed in the target repositories or organization

Best Practices:

  • Validate Early: Run setup immediately after configuring your GitHub App credentials to catch configuration errors early
  • Regenerate Keys Periodically: For security, periodically regenerate your GitHub App private key and update your integration
  • Test with Small Scope: Start with limited repository access during testing, then expand permissions as needed
  • Monitor Installations: Keep track of how many installations your App has. Unexpected changes may indicate security issues

Important Considerations:

The setup endpoint validates static configuration (App ID and private key) but does not test actual command execution. After setup succeeds, test your specific bot commands with real conversations to ensure full end-to-end functionality. Setup validation is a prerequisite but not a guarantee that all bot features will work correctly.

Deleting a GitHub Integration

Permanently remove a GitHub integration from your ChatBotKit account. This deletes the integration configuration but does not uninstall the GitHub App from your account or org. After deletion, the webhook endpoint becomes inactive and stops processing events.

Event Webhook Endpoint

Receives real-time events from GitHub (issue/PR comments) and summons the bot when it is @mentioned. Configure this URL as the webhook for your GitHub App or repository/org:

Subscribe to: issue_comment, pull_request_review_comment. Every request is verified against the integration's webhookSecret using the x-hub-signature-256 HMAC. Events are acknowledged immediately and processed asynchronously in the queue; GitHub redelivers on non-2xx (deduplicated via the x-github-delivery id).

Note that a PR's top-level comment arrives as issue_comment (a PR is an issue in GitHub's model) - distinguished by issue.pull_request being set.

Fetching Integration Details

Retrieve detailed configuration for a specific GitHub integration, including its GitHub App credentials.

Updating Integration Configuration

Modify an existing GitHub integration's configuration (bot, webhook secret, and options). Updates take effect immediately.

Listing GitHub Integrations

Retrieve a list of all GitHub integrations configured in your ChatBotKit account.

githubintegrationwebhookbot