Gitea (REST API)

Operate Gitea by sending HTTP requests to $GITEA_URL/api/v1/... authenticated by $GITEA_TOKEN. This skill does NOT depend on any MCP server — every operation is a direct curl call.

Keep this entry file small. Load only the reference pack the current turn needs.

Always-On Rules

0. Forced forge routing. Before any forge work, run git remote get-url origin and parse the host. If the host is github.com, this skill does not apply — use gh, including for internal GitHub organizations. For any other host, treat it as a Gitea candidate: derive https://<host> as the probe base URL, run curl -fsS --max-time 5 "https://<host>/api/v1/version", and use this skill only if HTTP 200 returns JSON with a version field. If the probe fails or times out, ask the user; do not guess another forge.
1. Resolve $GITEA_URL + $GITEA_TOKEN from named env pairs, not from the user. Each instance is exported as GITEA_<ALIAS>_URL + GITEA_<ALIAS>_TOKEN (e.g. GITEA_ORGA_URL + GITEA_ORGA_TOKEN). Call gitea_auto (defined in setup.md) to auto-pick the pair whose URL host matches the current repo's origin; falls back to the unaliased GITEA_URL/GITEA_TOKEN, then to gitea-mcp legacy GITEA_HOST/GITEA_ACCESS_TOKEN, then asks the user. $GITEA_URL is always the base URL without the /api suffix.
2. Send Authorization: token $GITEA_TOKEN on every request. Never put the token in the query string (?token=) — it would be logged.
3. Prefer curl -s piped to jq so results are easy to inspect. Always include -o /dev/null -w '%{http_code}\n' (or --fail-with-body) when verifying success on write/delete calls — Gitea returns success bodies on 2xx and a { "message": "...", "url": "..." } error envelope on 4xx/5xx.
4. Respect destructiveness. Any DELETE against /branches, /contents, /releases, /tags, labels, milestones, packages, secrets, variables, or wiki pages is irreversible. State exactly what will be removed and confirm with the user unless explicitly authorized.
5. Pagination: most list endpoints take ?page=N&limit=M (default page=1, limit=30, server max usually 50). A few older endpoints accept per_page= as an alias. Loop pages until the response is empty or Link: rel="next" is absent.
6. PUT /repos/{owner}/{repo}/contents/{path} (create/update file): content must be base64-encoded. Omit sha to create; pass the current file sha to update.
7. Endpoint responses are the resource directly — Gitea does not wrap them in { success, data }. Errors come back with HTTP 4xx/5xx plus { "message": "...", "url": "..." }.