---
description: "Instance-wide bug reports submitted via PostHog surveys. All authenticated users can view; System Administrators manage status."
---

# Bugtracker

Instance-wide bug reports submitted via PostHog surveys. All authenticated users can view; System Administrators manage status.

![Bugtracker](/documentation/blume-assets/content/docs/img/screenshots/13-audit-log.png)

## Overview

The **Bugtracker** page shows a table of all bug reports across the instance.

Columns:
- **Title** — From survey response
- **Status** — New / Fixed / Won't Fix
- **Reporter** — User who submitted (if identifiable)
- **Created** — Timestamp
- **Actions** — View details (all), Set status (System Admin)

## Viewing Bug Reports

1. Navigate to **Bugtracker** in sidebar (visible to all authenticated users)
2. Table loads automatically
3. Click **View details** on any row → dialog with full report


### Detail Dialog Shows

- Full bug description
- Reporter info (email, workspace, role)
- Browser/environment metadata
- Status + optional admin comment
- **System Admin**: Status dropdown + comment field

## Status Management (System Admin Only)

| Status | Meaning |
|--------|---------|
| **New** | Freshly submitted, not yet reviewed |
| **Fixed** | Issue resolved (code fix, config change, etc.) |
| **Won't Fix** | Not a bug, by design, or out of scope |

To update:
1. Open detail dialog
2. Select new status from dropdown
3. Optional: Add comment (visible in dialog)
4. Click **Save**

Changes audited in Audit Log (`bug_report.status_changed`).

## How Reports Are Created

### PostHog Survey Integration

1. User encounters issue → clicks "Report Bug" (or automatic prompt)
2. PostHog "Bug report" survey shown
3. User fills: title, description, severity, steps to reproduce
4. On submit → PostHog webhook → `POST /api/v1/bug-reports/webhook`
5. Bug report created in database

### Backfill Historical Reports

Use the `bugtracker-backfill` skill to import past survey responses:

```bash
# From PostHog MCP or script
python .opencode/skills/bugtracker-backfill/backfill.py
```

Ingestion has no deduplication — only replay responses not already present.

## API Endpoints

| Method | Path | Access |
|--------|------|--------|
| `GET` | `/api/v1/bug-reports` | All authenticated |
| `GET` | `/api/v1/bug-reports/{id}` | All authenticated |
| `PATCH` | `/api/v1/bug-reports/{id}` | System Admin |

### PATCH Body

```json
{
  "status": "fixed",
  "adminComment": "Fixed in v0.9.250 — was a race condition in SSE handler"
}
```

## Configuration

Environment variable:
- `BUGTRACKER_WEBHOOK_SECRET` — Validates PostHog webhook calls

## Permissions

| Role | Can View | Can Update Status |
|------|----------|-------------------|
| Member | ✅ | ❌ |
| Workspace Admin | ✅ | ❌ |
| System Admin | ✅ | ✅ |

## Recent Updates

- **Bugtracker Page** — Instance-wide bug reports table with detail dialog
- **PostHog Webhook** — Automatic ingestion from "Bug report" surveys
- **Status Workflow** — New → Fixed / Won't Fix with admin comments
- **Backfill Skill** — Import historical survey responses