---
name: gitea
description: Use for every forge operation in this repo — read, create, comment on, label, close, or search an issue; create, review, merge, or check out a PR; and whenever `gh`, `issue://`, or `pr://` fails or a ticket number is ambiguous. This repo's forge is self-hosted Gitea driven by `tea`, not GitHub.
---

# Gitea, not GitHub

`origin` is the self-hosted Gitea instance `gitea.violetcrown.my.id`, repo
`sulthan/mangaBookmark`. Everything past plain git goes through
[`tea`](https://gitea.com/gitea/tea) (0.14.2 on this machine).

**`gh` is not installed**, so the harness's `issue://<n>` and `pr://<n>` URIs
error out (`GitHub CLI (gh) is not installed`, measured 2026-08-17). There is no
fallback to add — read tickets with `tea`.

`tea` infers the repo from `origin`; auth lives in `tea login`, never a
`GH_TOKEN`. Your Gitea username comes from `tea login list` — `tea` has no `@me`.

Flags are the environment's job: run `tea <command> --help` rather than trusting
a remembered flag. This file carries only what `--help` will not tell you.

## Commands

| Job | Command |
|---|---|
| Read | `tea issue <n> --comments` / `tea pr <n> --comments` — `--comments` is not optional |
| List | `tea issue list --state open\|closed\|all -o json --fields index,title,body,labels,state,author` |
| Search | `tea issue list -k "<keyword>" -L "<label>" -A "<author>"` (`-K all` also searches PRs) |
| Create | `tea issue create -t "..." -d "..."` (`-L`, `-a` optional) |
| Comment | `tea comment <n> "..."` |
| Label | `tea issue edit <n> --add-labels "..."` / `--remove-labels "..."` |
| Close | `tea issue close <n>` / `tea pr close <n>` |
| PR | `tea pr create --head <branch> --base main -t "..." -d "..."`, `tea pr checkout <n>`, `tea pr review <n>`, `tea pr merge <n>` |

## Traps

- **A bare read is a truncated read.** Without `--comments`, `tea issue <n>` and
  `tea pr <n>` print the opening body and drop every comment silently — no
  prompt, no marker, no hint that more exists (measured 2026-08-17: issue #123
  prints 40 lines bare, 132 with `--comments`). The comments are where the
  decisions live and the body is usually the stalest part of the ticket, so
  **every read that exists to understand an issue or PR passes `--comments`**,
  and understanding means body plus all comments plus whatever ticket they point
  at. Comment count is `tea issue list --fields index,comments`, so a read that
  shows fewer than that is incomplete. A PR's review comments are a second
  stream: `tea pr review-comments <n>`.
- **One index space for issues and PRs.** A bare `#42` may be either: try
  `tea pr 42`, fall back to `tea issue 42`. Say which one you found.
- **Output is rendered boxes**, not plain text. Anything you parse needs
  `-o json`, plus `--fields` to keep the payload small. `tea pr create` prints
  the PR URL on its last line.
- **`close` takes no `--comment`.** Comment with `tea comment <n>`, then close.
- **Gitea will not auto-create a label.** `tea labels list` first; missing one
  gets `tea labels create --name "..." --color "#rrggbb"` before the `edit`.
- **Multi-line bodies go through a heredoc**, never inline escapes:
  ```bash
  tea issue create -t "Title" -d "$(cat <<'EOF'
  body line one

  - acceptance criterion
  EOF
  )"
  ```
- **No sub-issue and no dependency command.** Gitea's API has issue
  dependencies, `tea` does not expose them, so parentage and blocking live as
  body lines — the shapes are in `docs/agents/issue-tracker.md`.

## Conventions this repo layers on top

Ticket bodies, wayfinding issues, and the PR-as-request-surface flag:
`docs/agents/issue-tracker.md`. Triage label strings: `docs/agents/triage-labels.md`.
A label named there still has to exist in the tracker before `--add-labels`.

Finish a forge action by stating the number you touched and its state after —
"commented and closed #71" — so the write is checkable without a second query.