peregrine/docs/reference/forgejo-feedback-schema.md

Forgejo Feedback API — Schema & Bug Bot Setup

API Endpoints Used

Operation	Method	Endpoint
List labels	GET	/repos/{owner}/{repo}/labels
Create label	POST	/repos/{owner}/{repo}/labels
Create issue	POST	/repos/{owner}/{repo}/issues
Upload attachment	POST	/repos/{owner}/{repo}/issues/{index}/assets
Post comment	POST	/repos/{owner}/{repo}/issues/{index}/comments

Base URL: https://git.opensourcesolarpunk.com/api/v1

---

Issue Creation Payload

POST /repos/{owner}/{repo}/issues
{
  "title": "string",
  "body":  "markdown string",
  "labels": [1, 2, 3]   // array of label IDs (not names)
}

Response (201):

{
  "number": 42,
  "html_url": "https://git.opensourcesolarpunk.com/pyr0ball/peregrine/issues/42"
}

---

Issue Body Structure

The build_issue_body() function produces this markdown layout:

## 🐛 Bug | ✨ Feature Request | 💬 Other

<user description>

### Reproduction Steps          ← bug type only, when repro provided

<repro steps>

### Context

- **page:** Home
- **version:** v0.2.5-61-ga6d787f   ← from `git describe`; "dev" inside Docker
- **tier:** free | paid | premium
- **llm_backend:** ollama | vllm | claude_code | ...
- **os:** Linux-6.8.0-65-generic-x86_64-with-glibc2.39
- **timestamp:** 2026-03-06T15:58:29Z

<details>
<summary>App Logs (last 100 lines)</summary>

... log content (PII masked) ...

</details>

### Recent Listings             ← only when include_diag = True

- [Title @ Company](url)

---
*Submitted by: Name <email>*   ← only when attribution consent checked

---

Screenshot Attachment

Screenshots are uploaded as issue assets, then embedded inline via a follow-up comment:

### Screenshot

![screenshot](https://git.opensourcesolarpunk.com/attachments/<uuid>)

This keeps the issue body clean and puts the screenshot in a distinct comment.

---

Labels

Label	Color	Applied when
beta-feedback	#0075ca	Always
needs-triage	#e4e669	Always
bug	#d73a4a	Type = Bug
feature-request	#a2eeef	Type = Feature Request
question	#d876e3	Type = Other

Labels are looked up by name on each submission; missing ones are auto-created via _ensure_labels().

---

Bug Bot Account Setup

The token currently bundled in .env is pyr0ball's personal token. For beta distribution, create a dedicated bot account so the token has limited scope and can be rotated independently.

Why a bot account?

• Token gets bundled in beta testers' .env — shouldn't be tied to the repo owner's account
• Bot can be limited to issue write only (cannot push code, see private repos, etc.)
• Token rotation doesn't affect the owner's other integrations

Steps (requires Forgejo admin panel — API admin access not available on this token)

1. Create bot account at https://git.opensourcesolarpunk.com/-/admin/users/new

   • Username: peregrine-bot (or cf-bugbot)
   • Email: a real address you control (e.g. bot+peregrine@circuitforge.tech)
   • Set a strong password (store in your password manager)
   • Check "Prohibit login" if you want a pure API-only account

2. Add as collaborator on pyr0ball/peregrine:

   • Settings → Collaborators → Add peregrine-bot with Write access
   • Write access is required to create labels; issue creation alone would need only Read+Comment

3. Generate API token (log in as the bot, or use admin impersonation):

   • User Settings → Applications → Generate New Token
   • Name: peregrine-feedback
   • Scopes: issue (write) — no repo code access needed
   • Copy the token — it won't be shown again

4. Update environment:

   FORGEJO_API_TOKEN=<new bot token>
   FORGEJO_REPO=pyr0ball/peregrine
   FORGEJO_API_URL=https://git.opensourcesolarpunk.com/api/v1
   

   Update both .env (dev machine) and any beta tester .env files.

5. Verify the bot can create issues:

   curl -s -X POST https://git.opensourcesolarpunk.com/api/v1/repos/pyr0ball/peregrine/issues \
     -H "Authorization: token <bot-token>" \
     -H "Content-Type: application/json" \
     -d '{"title":"[TEST] bot token check","body":"safe to close","labels":[]}'
   

   Expected: HTTP 201 with number and html_url in response.

Future: Heimdall token management

Once Heimdall is live, the bot token should be served by the license server rather than bundled in .env. The app fetches it at startup using the user's license key → token is never stored on disk and can be rotated server-side. Track as a future Heimdall feature.