holocron/plugins/kyberforge/docs/research/docs/gitea/examples.md

topic, source_keys

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

Gitea MCP — Common Workflow Patterns

Canonical call sequences for the operations most likely to appear in a Gitea-managing skill.

Create an issue with labels and a milestone

Labels and milestones must be referenced by numeric ID in write operations. Resolve them first.

1. label_read  method: "list_repo_labels"  owner: "Defame1297"  repo: "holocron"
   → returns [{id: 3, name: "bug"}, {id: 7, name: "enhancement"}, ...]

2. milestone_read  method: "list"  owner: "Defame1297"  repo: "holocron"
   → returns [{id: 1, title: "v1.0"}, ...]

3. issue_write  method: "create"
     owner: "Defame1297"  repo: "holocron"
     title: "Fix the widget"
     body: "Description of the problem"
     labels: [3]          ← IDs, not names
     milestone: 1         ← milestone ID
     assignees: ["alice"]

Apply labels to an existing issue

1. label_read  method: "list_repo_labels"  owner: ...  repo: ...
   → map name → id for the labels you want

2. issue_write  method: "add_labels"
     owner: ...  repo: ...
     issue_number: 42
     labels: [3, 7]    ← IDs

To replace all labels atomically (remove existing, set new):

issue_write  method: "replace_labels"
  issue_number: 42
  labels: [3, 7]

To remove a single label:

issue_write  method: "remove_label"
  issue_number: 42
  label_id: 3    ← singular, not the array form

Create a feature branch, push a file, open a PR

1. create_branch
     owner: "Defame1297"  repo: "holocron"
     branch: "feat/my-feature"
     old_branch: "main"        ← defaults to repo default if omitted

2. get_file_contents  (only needed if updating an existing file)
     owner: ...  repo: ...  ref: "feat/my-feature"  path: "README.md"
     → note the sha field

3. create_or_update_file
     owner: ...  repo: ...
     path: "README.md"
     content: "<base64-encoded content>"
     message: "feat: update README"
     branch_name: "feat/my-feature"
     sha: "<sha from step 2>"    ← required when updating; omit only for new files

4. pull_request_write  method: "create"
     owner: ...  repo: ...
     title: "feat: my feature"
     body: "Description of changes"
     head: "feat/my-feature"
     base: "main"
     labels: [7]          ← label IDs, if desired
     milestone: 1
     reviewers: ["alice"]

Merge a PR and clean up

1. pull_request_read  method: "get_status"
     owner: ...  repo: ...  pull_number: 12
   → check that status is passing before merge

2. pull_request_write  method: "merge"
     owner: ...  repo: ...  pull_number: 12
     merge_style: "squash"           ← or "merge", "rebase", etc.
     message: "feat: my feature (#12)"
     delete_branch: true             ← clean up the feature branch post-merge

Close an issue when a PR merges

Issues are not automatically closed when a PR merges in Gitea (unlike GitHub). Close them explicitly after merge:

issue_write  method: "update"
  owner: ...  repo: ...
  issue_number: 5
  state: "closed"

Create and manage a milestone

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

2. Assign issues to it:
   issue_write  method: "update"
     issue_number: 42
     milestone: <id from step 1>

3. Close it when done:
   milestone_write  method: "update"
     id: <milestone id>
     state: "closed"

List open PRs linked to a milestone

list_pull_requests
  owner: ...  repo: ...
  state: "open"
  milestone: <milestone id>

Note: list_pull_requests response items carry milestone as a bare title string, not an object. You cannot filter by milestone ID from the PR list response alone — pass the milestone ID as a query parameter instead.

Resolve label name → ID without listing all labels

There is no direct lookup-by-name endpoint exposed through the MCP tools. The pattern is always:

label_read  method: "list_repo_labels"  per_page: 50
→ scan results for the target name → extract id

If you have more than 50 labels, paginate until found.

Submit a code review

1. pull_request_review_write  method: "create"
     pull_number: 12
     state: "PENDING"
     commit_id: "<head SHA from PR get response>"
     comments: [
       {path: "src/foo.go", body: "Consider extracting this", new_line_num: 42}
     ]
   → returns review_id

2. pull_request_review_write  method: "submit"
     pull_number: 12
     review_id: <from step 1>
     state: "REQUEST_CHANGES"
     body: "A few nits, see inline comments"

Update a file when you don't know the current SHA

SHA is mandatory for file updates. If you skipped storing it:

get_file_contents
  owner: ...  repo: ...
  ref: "main"
  path: "the/file.md"
→ extract sha from response

create_or_update_file
  ...
  sha: <extracted sha>

Do not guess or omit the SHA — the request will fail or create a duplicate.