---
name: gitea-files

description: >
  Use when reading or writing files or directories in a Gitea repository via the MCP server,
  rather than the local filesystem — even when the user does not say "Gitea". Not commit
  history -> `gitea-branches`. Not pull requests -> `gitea-prs`.

compatibility: Requires the Gitea MCP server configured with a token scoped to at least
  write:repository. Tested with a token holding write:issue + write:repository; write:issue
  is not actually required for any of this domain's five tools.

metadata:
  category: gitea
  source_keys:
    - gitea-mcp-repo
    - gitea-mcp-slim-go
    - context7-websites-gitea

allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__gitea__get_repository_tree mcp__gitea__create_or_update_file mcp__gitea__delete_file
---

## Gotchas

- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first.
- **Reads take `ref`, writes take `branch_name`.** One concept, two parameter names — chaining a read into a write drops the branch if you carry the wrong key.
- **`content` is base64 both ways.** Encode before a write, decode after a read.

## Inputs

`owner`, `repo` and the target branch are caller-supplied. This skill never infers them from a git remote: ask the human when they are not stated, and expect an orchestrating caller to have resolved them already.

## Dispatch

Read the reference for the row you land on before making the call.

| Condition | Flow | Reference |
|---|---|---|
| Read one file, list one directory level, or walk the repository tree | Read | `references/reading.md` — the three read tools, their pagination behaviour, and why neither a directory listing nor a tree entry supplies the SHA a write needs |
| Create, update, or delete a file | Write | `references/writing.md` — the SHA-first sequence every update and delete depends on, the worked multi-call sequence, and how to triage a write that fails |

A request that reads and then writes runs both flows in that order: fetch the file first, then write with the SHA that call returned.

## Handoff

Scope ends at the commit. Gitea's own web UI edits files directly against a branch, so committing straight to a branch is the normal path rather than an escape hatch — hand off to `gitea-prs` when the change needs review before merging or the target branch is protected, not by default.