# Issue tracker: Gitea (self-hosted)

Issues and PRDs for this repo live as **Gitea issues** on the self-hosted instance at
`git.mivanchenko.de`, repo **`BPPP/smb-online`**:
<https://git.mivanchenko.de/BPPP/smb-online/issues>

Gitea is not GitHub/GitLab, so `gh` / `glab` do **not** work here. Use the **Gitea REST API**
(or the [`tea`](https://gitea.com/gitea/tea) CLI, if installed). The API is GitHub-shaped.

## Auth

All write operations need a **personal access token with `issue` scope** (add `repository` scope
for label management). Generate one in the Gitea UI → *Settings → Applications → Generate New
Token* (scopes: `issue` Read+Write, `repository` Read+Write).

- **Never commit the token.** Keep it in the gitignored vault (`.secrets/`, e.g. `.secrets/gitea.env`
  as `GITEA_TOKEN=...`) and load it into the shell (`source .secrets/gitea.env`), or export it for
  the session. `.gitignore` already excludes `.secrets/`.
- A leaked token must be revoked in *Settings → Applications* and rotated.

Set these once per shell:

```bash
export GITEA_TOKEN=...              # from .secrets/, never inline in committed files
API=https://git.mivanchenko.de/api/v1/repos/BPPP/smb-online
AUTH="Authorization: token $GITEA_TOKEN"
```

## Conventions

- **Create an issue**:
  ```bash
  curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "$API/issues" \
    -d '{"title":"...","body":"...","labels":[<label-ids>]}'
  ```
  `labels` takes numeric **label IDs**, not names — list them first (see below). Use a heredoc /
  a JSON file for long bodies.
- **Read an issue**: `curl -s -H "$AUTH" "$API/issues/<number>"` ;
  comments: `curl -s -H "$AUTH" "$API/issues/<number>/comments"`.
- **List issues**: `curl -s -H "$AUTH" "$API/issues?state=open&limit=50"` (JSON). Filter with
  `&labels=<name>` and `&state=all|open|closed`.
- **Comment on an issue**:
  `curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "$API/issues/<number>/comments" -d '{"body":"..."}'`
- **Close an issue** (post the explanation first, then close):
  `curl -s -H "$AUTH" -H "Content-Type: application/json" -X PATCH "$API/issues/<number>" -d '{"state":"closed"}'`
- **Labels** — list: `curl -s -H "$AUTH" "$API/labels"` (gives id↔name). Create:
  `curl ... -X POST "$API/labels" -d '{"name":"...","color":"rrggbb","description":"..."}'`.
  Attach by id: `curl ... -X POST "$API/issues/<n>/labels" -d '{"labels":[<id>]}'`.

The `tea` CLI (`tea issue create|list|comment ...`) is a friendlier alternative once configured
against this instance with `tea login add`.

## Current label vocabulary

`bug` · `enhancement` · `security` · `ops` · `infra` · `crm` · `booking` · `n8n` · `tech-debt`
(list live IDs via `GET $API/labels`).

## When a skill says "publish to the issue tracker"

Create a Gitea issue via `POST $API/issues`.

## When a skill says "fetch the relevant ticket"

`GET $API/issues/<number>` plus `GET $API/issues/<number>/comments`.

## Pull requests as a request surface

**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature
requests; a triage skill would read this flag. Gitea PR endpoints mirror the issue ones under
`$API/pulls/...`.)_