Skip to main content
BugViper integrates with GitHub through a GitHub App — a first-class GitHub integration that acts under its own identity rather than a personal access token. The app receives webhook events when pull request comments are posted, clones repositories for analysis, and writes inline review comments back to your PRs. This guide walks you through creating the app, granting it the right permissions, and connecting it to your BugViper instance.

​
Step 1: Create a GitHub App

  1. Go to GitHub.com → your profile photo → Settings → Developer settings → GitHub Apps
  2. Click New GitHub App
  3. Fill in the app registration form:
    • GitHub App name: choose a unique name (e.g. bugviper-yourorg)
    • Homepage URL: the URL of your BugViper frontend (e.g. https://bugviper.yourcompany.com or http://localhost:3000 for local development)
    • Webhook URL: your BugViper instance URL followed by /api/v1/webhook/onComment — for example https://bugviper.yourcompany.com/api/v1/webhook/onComment
    • Webhook secret: generate a random secret string. You can use openssl rand -hex 20 to produce one
If you’re developing locally, GitHub can’t reach localhost to deliver webhooks. Use ngrok to expose your local BugViper API port (8000) to the internet. Reserve a static domain in the ngrok dashboard so your webhook URL stays the same across restarts. Set the ngrok URL as your Webhook URL and update it in your GitHub App settings whenever it changes.Set NGROK_DOMAIN in your .env and run ./start.sh to have BugViper start ngrok automatically.

​
Step 2: Set repository permissions

Under Permissions & events → Repository permissions, grant the following access levels:
PermissionAccess level
ContentsRead
IssuesRead & Write
Pull requestsRead & Write
MetadataRead
Commit commentsRead & Write
BugViper requires Read & Write on Pull requests and Commit comments to post inline review comments on your PRs. If either permission is set to Read-only or None, reviews will fail silently or produce an error when the agent tries to write a comment.
Subscribe to the following Webhook events:
  • Issue comment — triggers the review pipeline when @bugviper review is posted
  • Pull request — triggers incremental graph updates when a PR is merged
  • Push — triggers incremental graph updates when code is pushed to a branch

​
Step 3: Generate and download the private key

After saving the app:
  1. Scroll down to the Private keys section of your app’s settings page
  2. Click Generate a private key
  3. GitHub downloads a .pem file — save it somewhere safe on the server that runs BugViper (e.g. /etc/bugviper/your-app-name.private-key.pem)
The private key file grants access to your GitHub App. Never commit it to source control. The path you set in GITHUB_PRIVATE_KEY_PATH must be readable by the BugViper process at runtime.

​
Step 4: Install the app on your account or organization

  1. In your GitHub App settings, click Install App in the left sidebar
  2. Choose the account or organization where your repositories live
  3. Select All repositories or choose specific repositories you want BugViper to access
  4. Click Install

​
Step 5: Note your App ID

  1. Return to your GitHub App settings (Settings → Developer settings → GitHub Apps → your app)
  2. At the top of the page, copy the App ID — it’s a numeric value like 123456

​
Environment variables

Once you’ve created and installed the app, set these three variables in your .env file: 
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/path/to/your-app.private-key.pem
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here
GITHUB_APP_ID is the numeric ID from your app’s settings page. GITHUB_PRIVATE_KEY_PATH is the absolute path to the .pem file you downloaded. GITHUB_WEBHOOK_SECRET is the random string you generated when creating the app — it must match exactly what you entered in the GitHub App webhook configuration.

​
Verify the connection

After setting the environment variables and restarting BugViper, open a pull request on a repository the app has access to and post: 
@bugviper review
If the webhook is wired up correctly, BugViper adds a 🚀 reaction to your comment within a few seconds, indicating the review pipeline has started. If no reaction appears, check:
  • Your GitHub App webhook URL matches your BugViper instance URL + /api/v1/webhook/onComment
  • ngrok (or your reverse proxy) is running and forwarding traffic to the BugViper API port
  • The Recent Deliveries tab in your GitHub App settings shows the webhook was delivered successfully

​
Next step

Configure the remaining environment variables your BugViper instance needs:

Configure environment variables

Reference for all BugViper environment variables — Neo4j, OpenRouter, Firebase, and review agent settings.