From a17f65db22c0832e66708dfb0df11e2a369af2a4 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 5 Jul 2026 10:40:05 +0000 Subject: [PATCH] feat(gitea): add gitea-releases skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers releases and tags (list/get/create/delete) — all verified working with the current write:issue/write:repository token scope. --- plugins/gitea/skills/gitea-releases/README.md | 24 +++++++ plugins/gitea/skills/gitea-releases/SKILL.md | 52 +++++++++++++++ .../references/call-signatures.md | 66 +++++++++++++++++++ .../gitea-releases/references/conventions.md | 40 +++++++++++ .../gitea-releases/references/sources.md | 48 ++++++++++++++ 5 files changed, 230 insertions(+) create mode 100644 plugins/gitea/skills/gitea-releases/README.md create mode 100644 plugins/gitea/skills/gitea-releases/SKILL.md create mode 100644 plugins/gitea/skills/gitea-releases/references/call-signatures.md create mode 100644 plugins/gitea/skills/gitea-releases/references/conventions.md create mode 100644 plugins/gitea/skills/gitea-releases/references/sources.md diff --git a/plugins/gitea/skills/gitea-releases/README.md b/plugins/gitea/skills/gitea-releases/README.md new file mode 100644 index 0000000..83227d3 --- /dev/null +++ b/plugins/gitea/skills/gitea-releases/README.md @@ -0,0 +1,24 @@ +# gitea-releases + +Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags. + +## What it does + +This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work. + +## Usage + +``` +/gitea-releases +``` + +Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations. + +## Files + +| File | Purpose | +|------|---------| +| `SKILL.md` | Skill instructions for agents | +| `references/call-signatures.md` | Verified tool parameters and response shapes for all 9 release/tag tools | +| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior | +| `references/sources.md` | Research sources backing the call signatures and conventions | diff --git a/plugins/gitea/skills/gitea-releases/SKILL.md b/plugins/gitea/skills/gitea-releases/SKILL.md new file mode 100644 index 0000000..85f961a --- /dev/null +++ b/plugins/gitea/skills/gitea-releases/SKILL.md @@ -0,0 +1,52 @@ +--- +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. +- **`draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** 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` — it creates the underlying tag automatically if `tag_name` doesn't already exist, so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. 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`. diff --git a/plugins/gitea/skills/gitea-releases/references/call-signatures.md b/plugins/gitea/skills/gitea-releases/references/call-signatures.md new file mode 100644 index 0000000..c84ee3b --- /dev/null +++ b/plugins/gitea/skills/gitea-releases/references/call-signatures.md @@ -0,0 +1,66 @@ +--- +topic: call-signatures +source_keys: + - gitea-mcp-repo + - gitea-mcp-slim-go +--- + +# Release and tag call signatures + +Verified against the live MCP tool schemas at authoring time (not copied from upstream API docs, +which can drift from the deployed gitea-mcp version). `owner` and `repo` are required strings on +every tool below and are omitted from the per-tool lists for brevity. + +## Releases + +**`list_releases`** +- Optional: `is_draft` (boolean), `is_pre_release` (boolean), `page` (number, default 1), `per_page` (number, default 20) +- Returns an array of release objects (shape below), one page at a time. + +**`get_release`** +- Required: `id` (number) — the release's numeric id, not its tag name. +- Returns a single release object. + +**`get_latest_release`** +- No parameters beyond `owner`/`repo`. +- Returns a single release object for the most recently published (non-draft, non-prerelease by Gitea's own "latest" definition) release. + +**`create_release`** +- Required: `tag_name` (string), `target` (string — branch, tag, or commit SHA to cut the tag from), `title` (string) +- Optional: `body` (string — release notes), `is_draft` (boolean), `is_pre_release` (boolean) +- If `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call. + +**`delete_release`** +- Required: `id` (number) — same numeric id as `get_release`. Does not accept `tag_name`. +- Does not delete the underlying tag. + +**Release object shape** (returned by list/get/create/latest): +``` +id, tag_name, target, title, body, draft, prerelease, html_url, author, created_at, published_at +``` +`author` is the creator's login. `body` holds the release notes. + +## Tags + +**`list_tags`** +- Optional: `page` (number, default 1), `per_page` (number, default 20) +- Returns an array of `{ name, commit_sha }` — no `message` field on list responses. + +**`get_tag`** +- Required: `tag_name` (string) +- Returns `{ name, message, commit_sha }` — the only tag call that returns `message`. + +**`create_tag`** +- Required: `tag_name` (string) +- Optional: `target` (string — commitish to tag; if omitted, Gitea tags the default branch tip), `message` (string — annotated tag message) + +**`delete_tag`** +- Required: `tag_name` (string). Does not accept a numeric id. +- Does not delete any release wrapping the tag. + +## Pagination + +None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then +`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and +`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list +tools, so a caller assuming 30 will under-count pages needed for a fixed total. diff --git a/plugins/gitea/skills/gitea-releases/references/conventions.md b/plugins/gitea/skills/gitea-releases/references/conventions.md new file mode 100644 index 0000000..eb5690c --- /dev/null +++ b/plugins/gitea/skills/gitea-releases/references/conventions.md @@ -0,0 +1,40 @@ +--- +topic: conventions +source_keys: + - context7-websites-gitea + - context7-gitea-tea-cli +--- + +# Release and tag conventions + +Practitioner conventions that inform *how* to use the mechanics in `call-signatures.md` — not +additional tool schemas. + +## Release wraps a tag, not the reverse + +A release is a title, body (notes), and draft/prerelease flags layered on top of an existing or +newly-created tag. The tag is the git-level object (a name pointing at a commit); the release is a +Gitea-level metadata wrapper around it. This is why `delete_release` and `delete_tag` are separate +calls with separate identifiers (numeric id vs. tag name) — removing the wrapper never implies +removing the underlying pointer, and vice versa. + +## Semver tag naming + +Per the `tea` CLI (the reference Gitea client), tag names conventionally follow semver with a `v` +prefix: `v1.2.0`, `v2.0.0-beta.1`. This is a convention observed by tooling and humans, not a +Gitea-enforced constraint — the API accepts any string as `tag_name`. Don't validate or rewrite a +caller-supplied tag name against semver; just pass it through. + +## Draft and prerelease are explicit flags + +`draft` and `is_pre_release`/`prerelease` are booleans the caller sets directly on `create_release` +— Gitea does not infer either from the tag name, even though the `-beta`/`-rc` suffix convention +above is commonly used to signal a prerelease to humans. When a user asks to "cut a beta" or +"publish a release candidate," set `is_pre_release: true` explicitly in the same call rather than +relying on the tag string to carry that meaning. + +## Release notes sourcing + +Practitioner convention (per `tea`) is to source release notes (`body`) from a changelog file +rather than typing them inline for each release — useful context when a caller asks to "generate" +or "use the changelog for" release notes rather than write them from scratch. diff --git a/plugins/gitea/skills/gitea-releases/references/sources.md b/plugins/gitea/skills/gitea-releases/references/sources.md new file mode 100644 index 0000000..2b67a9f --- /dev/null +++ b/plugins/gitea/skills/gitea-releases/references/sources.md @@ -0,0 +1,48 @@ +# Sources + +## gitea-mcp-repo + +- **URL:** https://gitea.com/gitea/gitea-mcp +- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags. +- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags section); plugins/gitea/docs/research/docs/gitea/troubleshooting.md (`delete_release` numeric-id gotcha, `per_page` defaults) + +**Contributing files:** +- SKILL.md (Dispatch table, Gotchas) +- references/call-signatures.md + +**Status:** `extracted` + +## gitea-mcp-slim-go + +- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go +- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for tags and releases. +- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags response shapes) + +**Contributing files:** +- references/call-signatures.md (release/tag object shapes) + +**Status:** `extracted` + +## context7-websites-gitea + +- **URL:** context7:/websites/gitea +- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — release and tag semantics, draft/prerelease behavior. +- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section) + +**Contributing files:** +- SKILL.md (Gotchas — draft/prerelease as explicit flags) +- references/conventions.md + +**Status:** `extracted` + +## context7-gitea-tea-cli + +- **URL:** context7:/git_gitea_com/gitea_tea +- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner release/tag command patterns, semver tag conventions, draft/prerelease flags, release-notes-from-file conventions. +- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section) + +**Contributing files:** +- SKILL.md (Gotchas — semver tag naming) +- references/conventions.md + +**Status:** `extracted`