Configure BugViper GitHub webhooks

Set up GitHub webhooks to enable automatic push ingestion, PR merge graph updates, and @bugviper review triggers from pull request comments.

BugViper receives all events from GitHub through a single webhook endpoint on your server. When GitHub sends an event — a push to a branch, a PR being merged, or someone mentioning @bugviper in a comment — BugViper reads the X-GitHub-Event header and routes it to the right handler automatically. You configure this endpoint once in your GitHub App settings, and all three event types flow through it.

Webhook endpoint

All GitHub webhook events are handled by a single endpoint:

POST /api/v1/webhook/onComment

Point your GitHub App’s webhook URL to this path on your BugViper server. For example:

https://your-bugviper-domain.com/api/v1/webhook/onComment

Events handled

BugViper listens for three GitHub event types. You must subscribe to all three in your GitHub App settings.

push — incremental graph updates

When code is pushed to any branch, BugViper ingests the changed files into the Neo4j graph so your codebase index stays current.

• BugViper computes the diff between the before and after commit SHAs and updates only the affected nodes — it does not re-ingest the entire repository.
• If the pushed branch has an open pull request, ingestion is skipped. The PR review pipeline owns those changes; re-ingesting an unmerged branch mid-review would corrupt the graph.
• Pushes that create or delete a branch are ignored — use full ingestion for new branches.

pull_request (closed + merged) — merge graph updates

When a pull request is merged, BugViper updates the graph to reflect the merged changes.

• Only closed events where merged: true are processed; closed-without-merge events are ignored.
• This keeps your default branch graph accurate after every merge.

issue_comment — AI review trigger

When someone posts a comment on a pull request, BugViper checks whether the comment mentions @bugviper and contains a recognized review command.

• Comments from bots are filtered out automatically to prevent feedback loops.
• If the repository has not been indexed, BugViper posts a message on the PR instructing the author to ingest the repo first.
• If a review is already running for that PR, BugViper posts a message asking you to wait.

BugViper ignores comments from GitHub bots (accounts with type "Bot" or usernames containing [bot]). This prevents infinite loops if BugViper’s own comment happens to match a trigger pattern.

Review commands

Post either of these as a comment on a pull request where BugViper is installed:

Command	Behavior
@bugviper review	Incremental review — analyzes only the files changed in this PR
@bugviper full review	Full review — analyzes every file in the repository

The match is exact. Typos or extra words will result in an “Unrecognized command” response from BugViper on the PR. If that happens, delete your comment and post a corrected one.

Configuring your GitHub App

1. Open your GitHub App settings

   Go to your GitHub account or organization settings, then navigate to Developer settings → GitHub Apps. Click your BugViper app to open its settings page.

2. Set the webhook URL

   Under the Webhook section, set the Webhook URL to your BugViper server’s endpoint:

   https://your-bugviper-domain.com/api/v1/webhook/onComment
   

   Set Content type to application/json.

3. Set the webhook secret

   Enter a webhook secret in the Webhook secret field. This must match the value you set for GITHUB_WEBHOOK_SECRET in your .env file. BugViper uses this secret to verify that incoming payloads genuinely came from GitHub.

   Generate a strong secret with:

   openssl rand -hex 20
   
4. Subscribe to events

   Under Subscribe to events, enable all three of the following:

   • Push
   • Pull request
   • Issue comment

   Save your changes.

5. Verify required permissions

   Under Permissions & events → Repository permissions, confirm BugViper has at least:

   • Contents: Read
   • Issues: Read & Write
   • Pull requests: Read & Write
   • Metadata: Read
   • Commit comments: Read & Write

Local development with ngrok

During local development, GitHub cannot reach your laptop directly. Use ngrok to create a secure tunnel from a public URL to your local server.

1. Reserve a stable domain

   Log in to the ngrok dashboard and reserve a free static domain under Cloud Edge → Domains. A reserved domain keeps your webhook URL stable across ngrok restarts — you only need to update your GitHub App once.

2. Start the tunnel

   Run ngrok pointing at BugViper’s API port:

   ngrok http 8000 --domain=your-reserved-domain.ngrok-free.app
   
3. Update your GitHub App webhook URL

   In your GitHub App settings, set the webhook URL to:

   https://your-reserved-domain.ngrok-free.app/api/v1/webhook/onComment
   
4. Set NGROK_DOMAIN in your .env

   Add your reserved domain so the ./start.sh all-in-one script can launch ngrok automatically:

   NGROK_DOMAIN=your-reserved-domain.ngrok-free.app
   

Verifying webhook delivery

After pushing a commit or posting a @bugviper review comment, you can confirm the webhook was received by checking Recent Deliveries in your GitHub App settings. Each delivery shows the event type, payload, and the HTTP response BugViper returned. A 200 response with "status": "processing" means the event was accepted. A 200 with "status": "ignored" means BugViper received the event but intentionally skipped it (for example, a push to a branch with an open PR).