pyr0ball
3458122537
Some checks failed
CI / test (push) Failing after 21s
- Rename setup.sh to install.sh (standardise with cf-orch installer pattern) - Remove hardcoded dev-machine path from activate_git_hooks(); go straight to .githooks/ core.hooksPath fallback — the absolute path was only valid on the author's machine and surprised self-hosters - Add capture_license_key(): optional CFG-XXXX-… prompt after setup_env(), writes CF_LICENSE_KEY + HEIMDALL_URL into .env when a valid key is entered - Fix next-steps port: read STREAMLIT_PORT from .env instead of hardcoding 8501 (Docker default is 8502; users who customise the port saw a wrong URL) - Update .env.example: STREAMLIT_PORT=8502 (Docker default, not bare-metal 8501) - Fix stale git clone URL in docs/getting-started/installation.md: git.circuitforge.io → git.opensourcesolarpunk.com/Circuit-Forge/peregrine - Update all setup.sh references across manage.sh, Makefile, CONTRIBUTING.md, README.md, and docs/ to install.sh Closes #71
157 lines
4.6 KiB
Markdown
157 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```json
|
|
POST /repos/{owner}/{repo}/issues
|
|
{
|
|
"title": "string",
|
|
"body": "markdown string",
|
|
"labels": [1, 2, 3] // array of label IDs (not names)
|
|
}
|
|
```
|
|
|
|
Response (201):
|
|
```json
|
|
{
|
|
"number": 42,
|
|
"html_url": "https://git.opensourcesolarpunk.com/pyr0ball/peregrine/issues/42"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Issue Body Structure
|
|
|
|
The `build_issue_body()` function produces this markdown layout:
|
|
|
|
```markdown
|
|
## 🐛 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:
|
|
|
|
```markdown
|
|
### Screenshot
|
|
|
|
|
|
```
|
|
|
|
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:
|
|
```bash
|
|
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.
|