holocron/plugins/gitea/.apm/skills/gitea-issues/SKILL.md at dd1981db80743607281459782f9cb6d625d1bdd1

Files

Defame1297 dd1981db80 fix(gitea-issues): list_issues does have type and milestones on v1.7.0

SKILL.md's headline Gotcha said `list_issues` "has no `type` filter", and
references/issues.md stated in bold that neither `type` nor `milestones`
exists, "despite both appearing in api-reference.md". Both parameters are
present on the deployed gitea-mcp v1.7.0 and both work: `type: "issues"`
returns only issues, `type: "pulls"` only PRs, and `milestones` filters by
name. Unfiltered, the same window returns them interleaved, so the mixing
the Gotcha describes is real — only the stated remedy was wrong.

This mattered most in gitea-workflow's no-args check-in, which lists open
issues through this skill and so reported PRs under "Open Issues" while
the skill forbade the one-parameter fix. The list flow now passes
`type: "issues"`.

references/sources.md recorded the absence as a live-verification win over
stale research docs; it now records that the earlier check was superseded
by v1.7.0, since drift runs in both directions. gitea-prs cited the same
parameter as its canonical drift example and no longer does — no
replacement example was substituted, because the obvious candidate was not
verified in this pass.

Also defaults label writes to `add_labels`: `replace_labels` clears every
label not in the array, and per-label exclusivity makes blanket replacement
destructive for a non-exclusive scope.

Verified live against gitea-mcp v1.7.0, read-only calls.

Refs #99

2026-08-30 20:51:02 +00:00

4.4 KiB

Raw Blame History

name, description, compatibility, metadata, allowed-tools

name

description

compatibility

metadata

allowed-tools

gitea-issues

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`.

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.

Gotchas

list_issues mixes in PRs unless you filter. Issues and PRs share one repo number space; pass type: "issues" to exclude PRs (or "pulls" for only PRs). Nothing on a list item flags which is which — is_pull appears only on issue_read method: "get", never on a list item.
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:

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 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; every other row goes straight to its reference.

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.
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.
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.

4.4 KiB Raw Blame History