feat(gitea): add gitea-releases skill
Covers releases and tags (list/get/create/delete) — all verified working with the current write:issue/write:repository token scope.
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
48
plugins/gitea/skills/gitea-releases/references/sources.md
Normal file
48
plugins/gitea/skills/gitea-releases/references/sources.md
Normal file
@@ -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`
|
||||
Reference in New Issue
Block a user