---
name: gitea-issues

description: >
  Use when reading or writing Gitea issues — 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.3"
  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` returns PRs too.** It has no `type` filter and both share one repo number space. `is_pull` appears only on `issue_read method: "get"`, never on a list item — check it there before treating a number as an issue.
- **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 merged PR leaves its issue open.** Gitea does not auto-close on merge the way GitHub does. Re-read the issue's state after a merge before closing it manually.
- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist.

## Step 1 — Resolve owner and repo

An orchestrating caller may pass `owner` and `repo` in already; if so, skip this. The `search` row is cross-repository and needs only a query, so it skips this too. Otherwise, before any tool call:

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

If origin is unset or the URL is 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, 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; every other row goes straight to its reference.

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.