holocron/plugins/gitea/skills/gitea-labels-milestones/references/milestones.md

topic, source_keys

topic	source_keys
milestones	gitea-mcp-repo gitea-mcp-slim-go

Milestone operations

Execution detail for milestone_read and milestone_write. Milestones are always repo-scoped — there is no org-level milestone concept, unlike labels.

Verified live schemas

milestone_read — required: method, owner, repo.

Param	Type	Notes
method	string (enum)	"get" | "list"
owner	string	required
repo	string	required
id	number	milestone ID, required for "get"
name	string	title filter, for "list"
state	string	default "all" — conventional values "open"/"closed"/"all", but not enforced by an enum in the live schema (plain string). Any other value is passed through to Gitea rather than rejected client-side.
page	number	default 1
per_page	number	default 30

milestone_write — required: method, owner, repo.

Param	Type	Notes
method	string (enum)	"create" | "update" | "edit" | "delete" — "update"/"edit" are aliases for the same operation; prefer "update"
owner	string	required
repo	string	required
id	number	required for update/delete
title	string	required for create
description	string	optional
due_on	string	due date — the live tool schema only describes this as an opaque "due date" string with no enforced format; ISO 8601 (e.g. "2025-03-01T00:00:00Z") is the conventional value Gitea's REST API accepts, not something confirmed by the live MCP schema itself
state	string (enum)	"open" | "closed" — this one is schema-enforced, unlike milestone_read's state

Note: unlike label_read/label_write, both milestone tools hard-require owner and repo at the schema level — there's no scope variant to omit them for.

List milestones

milestone_read  method: "list"  owner: <owner>  repo: <repo>  state: "open"

Report each as: id, title, state, due date, open/closed issue counts.

Get one milestone

milestone_read  method: "get"  owner: <owner>  repo: <repo>  id: <id>

Resolve a milestone ID from a title

Needed whenever the only handle available is a title — e.g. a pull_request_read response, which returns milestone as a bare title string rather than {id, title}. Call:

milestone_read  method: "list"  owner: <owner>  repo: <repo>  name: <title>

and take the id of the matching result. If name filtering returns no match (e.g. due to a title typo or case mismatch), fall back to listing without the filter and matching manually.

Create a milestone

milestone_write  method: "create"
  owner: <owner>  repo: <repo>
  title: "v1.0"
  description: "First stable release"
  due_on: "2025-03-01T00:00:00Z"

Report the returned ID — the caller (gitea-issues/gitea-prs) needs it to assign issues/PRs to this milestone via issue_write/pull_request_write.

Update or close a milestone

milestone_write  method: "update"  owner: <owner>  repo: <repo>  id: <id>  state: "closed"

Only pass the fields being changed — id plus any of title/description/due_on/state.

Delete a milestone

milestone_write  method: "delete"  owner: <owner>  repo: <repo>  id: <id>

Deleting a milestone does not delete or unassign the issues/PRs that referenced it — they simply lose the milestone reference.