How senapati484/gitguard works
GitGuard is a GitHub App that reviews pull requests and pushes for leaked secrets, correctness defects, and exploitable security issues, then reports a PASS/WARN/BLOCK verdict through GitHub checks and review feedback. Its main workflow is webhook verification, queued background processing, parallel agent analysis, and verdict publication; users can also trigger scans and remediation. The dashboard exposes run health, policy, and alert controls. The README documents agent behavior and worker flow, but some cited agent files are absent from the tree, so their internals are represented only at the documented subsystem level.
Main entry points: orchestrator.ts Agent Orchestrator · firebase-admin.ts Firebase Services · route.ts Webhook Handler · page.tsx Dashboard
Components 24
GitHub Intake
- Webhook Handler
app/api/webhooks/github/route.ts - Signature Verification
lib/verify-webhook.ts - GitHub Event Queue
lib/queues/github-events.ts - Background Worker
worker.ts
Review Pipeline
- GitHub App Client
lib/github-app.ts - Agent Orchestrator
agents/orchestrator.ts - Secret Scanner
agents - Bug Agent
agents/bug-agent.ts - Security Agent
agents/security-agent.ts
Dashboard and Controls
- Dashboard
app/(dashboard)/dashboard/page.tsx - Manual Scan API
app/api/installations/[id]/scan/route.ts - Auto-Solve API
app/api/installations/[id]/auto-solve/route.ts - GitHub Remediation
lib/auto-solve-git.ts - Team Policy API
app/api/installations/[id]/policy/route.ts
Identity and State
- Session Authentication
lib/auth-session.ts - Firebase Services
lib/firebase-admin.ts - Marketplace Plans
lib/plan-limits.ts
Health and Alerts
- Health Reporting
agents/health-agent.ts - Health Badge API
app/api/badge/[installationId]/[repo]/route.ts - Alert Settings API
app/api/settings/[installationId]/route.ts - Email Alerts
agents/email-agent.ts
Other components
- Repository Admin
- GitHub
- Checks and Reviews
Connections 29
- GitHub → Webhook Handler: sends events
- Webhook Handler → Signature Verification: verifies signature
- Webhook Handler → GitHub Event Queue: enqueues events
- GitHub Event Queue → Background Worker: dispatches jobs
- Background Worker → GitHub App Client: fetches repository data
- Background Worker → Agent Orchestrator: runs review
- Agent Orchestrator → Secret Scanner: runs parallel scan
- Agent Orchestrator → Bug Agent: runs parallel scan
- Agent Orchestrator → Security Agent: runs parallel scan
- Agent Orchestrator → Checks and Reviews: publishes verdict
- Checks and Reviews → GitHub: reports checks
- Repository Admin → Dashboard: views results
- Dashboard → Manual Scan API: requests scan
- Manual Scan API → GitHub Event Queue: enqueues scan
- Dashboard → Auto-Solve API: requests remediation
- Auto-Solve API → GitHub Remediation: applies fixes
- GitHub Remediation → GitHub App Client: commits remediation
- Auto-Solve API → Firebase Services: updates run state
- Auto-Solve API → Health Reporting: recalculates score
- Dashboard → Team Policy API: manages policy
- Team Policy API → Firebase Services: reads and writes policy
- Repository Admin → Session Authentication: signs in
- Session Authentication → Firebase Services: verifies session
- Health Badge API → Health Reporting: requests report
- Health Reporting → Firebase Services: reads run history
- Repository Admin → Alert Settings API: configures alerts
- Alert Settings API → Email Alerts: saves settings
- Webhook Handler → Marketplace Plans: handles purchase events
- Marketplace Plans → Firebase Services: updates plan state