📖 Complete User Guide

🤖 What is bugsift?

Think of bugsift as an AI-powered triage bot for your GitHub issues. Instead of maintainers spending hours reading every issue to figure out if it's a real bug, duplicate, feature request, or spam — bugsift does this automatically in about 90 seconds per issue.

It classifies the issue, checks for duplicates, tries to reproduce it, and drafts a reply for you to approve. You always decide what actually gets posted.

✅ Prerequisites - What You Need

Hardware

• A server or cloud VM (AWS EC2, DigitalOcean, or even your laptop)
• 2GB RAM minimum (4GB recommended for production)
• 50GB disk space (scales with your repo size)
• Any OS: Linux, macOS, Windows (with Docker Desktop)

Software

• Docker 24+ (includes Docker Compose)
• Your own domain (optional for testing, required for production)
• A GitHub account with at least one repository

API Keys (you provide these)

• GitHub Personal Access Token (or GitHub App — we help you create this)
• LLM API key (Anthropic Claude, OpenAI, Google Gemini, or Ollama)

🚀 Installation - The Easy Way

The entire installation is literally one command:

What this does behind the scenes:

• Downloads pre-built Docker images (backend + frontend)
• Creates a PostgreSQL database
• Sets up Redis caching
• Generates encryption keys automatically
• Creates an nginx reverse proxy
• Starts all services
• Prints you a bootstrap token and dashboard URL

The entire process takes about 5 minutes.

For local testing (before production):

You can skip the domain and just run the command without the BUGSIFT_DOMAIN variable. This runs on localhost:3001 (frontend) and localhost:8001 (API).

⚙️ Initial Setup - First 15 Minutes

Once installed, here's what to do:

📊 Daily Workflow - What Actually Happens

Here's the magic part. A user creates an issue on your repo:

Within ~90 seconds, bugsift automatically:

• Classifies it — Determines it's a "bug" (not feature, question, docs, spam)
• Checks for duplicates — Searches past issues to see if this was reported before
• Points to likely files — Says "probably src/db/connection.py lines 45–78"
• Tries to reproduce — Runs code in isolated sandbox to confirm the bug
• Drafts a reply — Something like: "Thanks for the report! I can reproduce this on v1.2.3. It's because the connection pool doesn't handle network timeouts. Assigned to @alice."

This all appears as a triage card in the bugsift dashboard.

You (the maintainer) decide:

• ✅ Approve — Posts the comment to GitHub
• ✏️ Edit — Tweak the comment, then approve
• ⏭️ Skip — Ignore it (maybe it's unclear or you already have context)

All of this takes about 30 seconds for you to review. The bot does 90 seconds of work, you do 30 seconds.

🔌 Integrations - Connect to Your Tools

By default, bugsift shows you cards in the dashboard. But you can integrate:

GitHub (built-in)

• Posts the triaged comment to the actual GitHub issue
• Can auto-assign to team members
• Can add labels

Slack (optional)

• Sends you notifications when new triage cards appear
• Can filter by severity
• Links directly to dashboard cards

Jira (optional)

• Creates Jira tickets from approved GitHub issues
• Syncs status between GitHub and Jira
• Auto-assign based on your rules

Email (optional)

• Daily digest of what was triaged
• Summary of accuracy

Set all of this up in Settings → Integrations.

📋 Configuration - Customizing Behavior

Routing Rules (the cool part)

You can tell bugsift custom rules like:

You define these rules once, bugsift applies them automatically.

Learning from your team

Every time you approve/edit/skip a card, bugsift learns. So if you consistently change "maybe-duplicate" to "actual-duplicate", bugsift gets better at catching duplicates. This is the "feedback loop" — the AI learns your team's preferences over time.

🔍 Monitoring - How is it Running?

The dashboard shows you:

• Metrics — How many issues were triaged today, approval rate, accuracy
• LLM costs — How much you're spending per provider/model
• Performance — Average time to triage, success rate
• User activity — Who approved what, when

You can also:

• Check logs if something breaks (Settings → Logs)
• View audit trail of who did what and when (Settings → Audit Log)
• Export data for reporting

❓ Frequently Asked Questions

📚 Advanced Topics

Custom Prompts

The LLM prompts that drive classification, dedup, and reply generation are customizable. Fork the repo and modify them to match your team's style and preferences.

Self-Hosted Runners

For air-gapped environments or on-prem deployments, you can run bugsift entirely on your own hardware with no external dependencies.

Multi-Team Setup

Run one bugsift instance and manage multiple repos with different teams. Each team gets its own dashboard, rules, and audit log.

API Integrations

Bugsift exposes a REST API for advanced integrations. Check the GitHub repo for API docs.

🆘 Troubleshooting

Dashboard not loading

Check that Docker containers are running: docker ps. If the frontend container isn't running, check logs with docker logs bugsift-frontend.

No triage cards appearing

Make sure the GitHub App is installed on your repos (GitHub → Settings → Apps → Installed Apps). Check that new issues trigger webhooks (GitHub → Repo → Settings → Webhooks).

GitHub auth failing

Re-register the GitHub App in Settings → GitHub Integration → Register GitHub App. This will renew the App credentials.

LLM key invalid

Double-check your API key in Settings → LLM Provider. Make sure there are no extra spaces or line breaks. Test the key by triggering a triage.

Performance issues

If triages are slow, check that you have at least 2GB of available RAM. Consider upgrading to 4GB for production use. Also check LLM provider status — slow responses usually mean the provider is under heavy load.

💡 The Key Insight

What makes bugsift different from other tools is it's human-in-the-loop by design. Users aren't handing off decision-making to AI. They're using AI to do the boring reading/analysis work, then they make the actual decisions. This is why it's safe and practical to use in real teams.