---
name: gitea-issues

description: >
  Use when reading or writing Gitea issues — "create an issue", "what issues are open",
  "close issue #N", "comment on issue #N", "label issue #N", "search issues for X" — even when
  the user does not say "Gitea". Not pull requests -> `gitea-prs`.
  Not label or milestone definitions -> `gitea-labels-milestones`.

compatibility: Requires Gitea MCP server configured with write:issue and write:repository token
  scopes. Requires git remote "origin" pointing to the Gitea instance for owner/repo resolution
  when invoked directly by a human; an orchestrating caller (e.g. gitea-workflow) may pass
  owner/repo already resolved.

metadata:
  category: integration
  version: "0.1.5"
  source_keys:
    - gitea-mcp-repo
    - gitea-mcp-slim-go
    - context7-websites-gitea
    - context7-gitea-tea-cli

allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__issue_write mcp__gitea__search_issues
---

## Gotchas

- **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`).
- **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels.
- **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually.
- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist.

## Step 1 — Resolve owner and repo

Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call:

```bash
rtk git remote get-url origin
```

No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."

## Step 2 — Dispatch

One invocation takes one row. Read only the reference(s) that row names — the call signatures were verified against the live MCP schema and differ from the published API docs in ways the body does not restate.

| Invocation | Flow | Read |
|---|---|---|
| `/gitea-issues` or `/gitea-issues list` | List issues with `type: "issues"` so PRs are excluded, optionally filtered by state | `references/issues.md` |
| `/gitea-issues <N>` | Get one issue, routing to `gitea-prs` when the number turns out to be a PR | `references/issues.md` |
| `/gitea-issues <N> comments` | Get an issue's comments | `references/issues.md` |
| `/gitea-issues <N> labels` | Get an issue's labels as full objects, IDs included | `references/issues.md` |
| `/gitea-issues close <N>` | Close an issue by updating its state | `references/issues.md` |
| `/gitea-issues comment <N>` | Add a comment drawn from conversation context, never one invented to fill the gap — a comment on a live issue is not cheap to undo | `references/issues.md` |
| `/gitea-issues label <N>` | Apply, replace or remove labels using IDs resolved by `gitea-labels-milestones` | `references/issues.md` |
| `/gitea-issues create` | Create an issue — Step 3 first | `references/enrichments.md`, then `references/issues.md` |
| `/gitea-issues search <query>` | Cross-repo search, narrowed by owner, state, type or labels | `references/search.md` |

## Step 3 — Create

Only the create flow reaches this step.

1. Take `title` and `body` from conversation context — the most recent task, bug report, or explicit statement. An empty body is an acceptable fallback, an invented one is not.
2. Run the enrichments in `references/enrichments.md`, then create with the resolved IDs per `references/issues.md`. Omitting a parameter always beats guessing its value — a wrong milestone or assignee is harder to notice than a missing one.
3. Fire immediately, with no confirmation step. A create is cheap to undo by closing, so a gate here only costs a round trip.

## Step 4 — Report

Reads: a compact table or numbered list — number, title, state, labels, milestone.

Writes: what was created or updated, with the issue number and the URL when one is returned.

Errors: the HTTP code and message as returned, without paraphrasing either.