holocron/plugins/gitea/skills/gitea-branches/SKILL.md

name, description, compatibility, metadata, allowed-tools

name	description	compatibility	metadata	allowed-tools
gitea-branches	Use when managing Gitea repository branches — listing, creating, or deleting branches — or inspecting commit history within a Gitea repo: listing commits (optionally filtered by branch or file path) or getting full detail for a single commit by SHA. Triggers on "list branches", "create a branch", "delete a branch", "what commits are on this branch", "show commit <sha>", "what changed in that commit" — even if the user doesn't say "Gitea" explicitly, as long as the repo's remote is a Gitea instance. Do not use for local git branch/commit operations on your working copy (use git-branches or git-history) or for PR-side branch references like cross-repo fork PR heads (use gitea-prs).	Requires Gitea MCP server configured with a token; list_branches, list_commits, and get_commit work with write:issue alone, create_branch and delete_branch require write:repository. Requires git remote "origin" pointing to the Gitea instance.	category version source_keys integration 0.1.0 gitea-mcp-repo gitea-mcp-slim-go context7-websites-gitea	Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__gitea__delete_branch mcp__gitea__list_commits mcp__gitea__get_commit

Gotchas

• Never delete a protected branch (main/master by name, or protected: true from list_branches) without explicit confirmation. delete_branch is a direct API call, not a local git push — there is no client-side force-push guard protecting it. Name-matching main/master is a convenient default but not authoritative — a repo can protect a differently-named default branch. When in doubt, call list_branches first and check protected on the target; treat deletion of any protected branch as a hard refusal unless the user explicitly confirms in the conversation.
• 404 may actually mean 403. Gitea hides permission errors as not-found to avoid leaking resource existence. If any of these five tools returns 404 unexpectedly, check token scope (see references/branches.md / references/commits.md) before concluding the branch or commit doesn't exist.
• Pagination is manual. list_branches and list_commits return one page at a time — no auto-pagination in the MCP layer. When you need a complete list, iterate page: 1, 2, ... until the returned count is less than per_page.
• Owner/repo always come from the git remote, never from get_me. Resolve them via git remote get-url origin (Step 1 below). get_me/list_my_repos are blocked under the token scopes this skill assumes.
• create_branch's source is old_branch, not "wherever gitea-mcp feels like." Omitting old_branch forks from the repo's server-side default branch — not necessarily the branch you're currently working on locally. If you want to branch from your current checkout, pass old_branch explicitly.

Step 1 — Resolve owner and repo

Before any tool call, extract owner and repo from the git remote:

git remote get-url origin

If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."

Step 2 — Dispatch

Invocation	Action
/gitea-branches or /gitea-branches list	List branches
/gitea-branches create <name> [from <base>]	Create branch
/gitea-branches delete <name>	Delete branch
/gitea-branches commits [on <branch>] [touching <path>]	List commit history
/gitea-branches commit <sha>	Get full detail for one commit

For branch operations (list/create/delete), read references/branches.md. For commit operations (list/get), read references/commits.md.

Step 3 — Report

For reads: display branches as name + protected flag; display commits as SHA (short), message summary, author, date.

For writes (create/delete): confirm the action taken, the branch name, and (for create) the base it forked from.

For errors: surface the HTTP code and message. If a 404 is unexpected, re-check token scope per the Gotchas above before reporting "not found" to the user.