Defame1297
940e414980
An audit against plugins/gitea/docs/research/docs/gitea/*.md found the gitea-releases skill told callers to set create_release's draft flag as `draft` instead of `is_draft` (the actual input param; `draft` is only the response field name) - a call following that gotcha would have the flag silently ignored, publishing a non-draft release. Also corrected an overclaimed "verified against live MCP schema" provenance note in call-signatures.md/README.md (its sources are gitea-mcp source-code extraction, not a live tool call - now noted alongside a narrow live ToolSearch cross-check performed this session for 3 of the 9 tools' input params), and softened three behavioral claims (create_release auto-creating tags, get_latest_release excluding drafts/prereleases, delete_tag preserving a wrapping release) that don't trace to any research doc, with a recommendation to verify release/tag state after delete operations rather than assume it.
53 lines
5.0 KiB
Markdown
53 lines
5.0 KiB
Markdown
---
|
|
name: gitea-releases
|
|
|
|
description: >
|
|
Use when managing Gitea releases and tags for a repository: listing, creating, or deleting
|
|
releases (with draft/prerelease flags and release notes), and listing, creating, or deleting the
|
|
underlying git tags. Use even if the user doesn't say "release" explicitly — "cut a v1.2.0",
|
|
"publish a prerelease", "tag this commit", or "what's the latest release" all apply. Do not use
|
|
for git branch or commit history operations (use gitea-branches) or for issue/PR management (use
|
|
gitea-issues / gitea-prs).
|
|
|
|
metadata:
|
|
category: gitea
|
|
source_keys:
|
|
- gitea-mcp-repo
|
|
- gitea-mcp-slim-go
|
|
- context7-websites-gitea
|
|
- context7-gitea-tea-cli
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand.
|
|
- **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately.
|
|
- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. There is no auto-pagination in the MCP layer — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
|
|
- **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name.
|
|
- **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it.
|
|
|
|
## Dispatch table
|
|
|
|
| Action | Tool | Required params | Optional params |
|
|
|---|---|---|---|
|
|
| List releases | `list_releases` | `owner`, `repo` | `is_draft`, `is_pre_release`, `page` (default 1), `per_page` (default 20) |
|
|
| Get one release | `get_release` | `owner`, `repo`, `id` (number) | — |
|
|
| Get latest release | `get_latest_release` | `owner`, `repo` | — |
|
|
| Create release | `create_release` | `owner`, `repo`, `tag_name`, `target`, `title` | `body`, `is_draft`, `is_pre_release` |
|
|
| Delete release | `delete_release` | `owner`, `repo`, `id` (number) | — |
|
|
| List tags | `list_tags` | `owner`, `repo` | `page` (default 1), `per_page` (default 20) |
|
|
| Get one tag | `get_tag` | `owner`, `repo`, `tag_name` | — |
|
|
| Create tag | `create_tag` | `owner`, `repo`, `tag_name` | `target`, `message` |
|
|
| Delete tag | `delete_tag` | `owner`, `repo`, `tag_name` | — |
|
|
|
|
`target` (on `create_release`/`create_tag`) is a commitish — a branch name, existing tag, or commit SHA — the point the new tag is cut from. See `references/call-signatures.md` for response shapes.
|
|
|
|
## Workflow
|
|
|
|
- [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference.
|
|
- [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`.
|
|
- [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation.
|
|
- [ ] **Listing completely:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
|
|
|
|
If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`.
|