holocron/plugins/gitea/skills/gitea-files/references/writing.md

source_keys

source_keys
gitea-mcp-repo gitea-mcp-slim-go

Creating, updating and deleting files

sha is the optimistic-concurrency token for every write, and it comes from get_file_contents's top-level sha field — never from content.sha, a directory listing, or a tree entry. Do not guess or reuse a stale value: a mismatched SHA is rejected exactly like a missing one.

content is base64-encoded, and the branch the commit lands on is branch_name, not ref.

Create a new file

Call create_or_update_file(owner, repo, path, content, message, branch_name) with sha omitted entirely. An omitted sha always means create, so the call returns HTTP 409 if the path already exists.

To branch off as part of the same write, pass new_branch_name: the branch is created and the commit lands on it in one call, replacing a separate branch-creation step.

Update an existing file

1. get_file_contents(owner, repo, ref: <branch>, path) → read the top-level sha.
2. create_or_update_file(owner, repo, path, content, message, branch_name, sha: <that value>).

Delete a file

Same SHA-first pattern, with no create-style fallback. sha is schema-required on delete_file, unlike create_or_update_file where omitting it means create — so an omitted sha is rejected client-side by input validation and the call never reaches Gitea. The HTTP 422 that is actually reachable here is the stale-sha case.

1. get_file_contents(owner, repo, ref: <branch>, path) → read the top-level sha.
2. delete_file(owner, repo, path, message, branch_name, sha: <that value>).

Worked sequence — new file on a new branch, then a PR

1. create_or_update_file
     owner, repo
     path: "docs/example.md"
     content: "<base64-encoded content>"
     message: "docs: add example"
     branch_name: "main"
     new_branch_name: "feat/add-example"   ← branches off before the commit lands
     (sha omitted — this is a new file)

2. Hand off to gitea-prs to open a PR from "feat/add-example" into "main".

Step 1 needs no preceding read: a brand-new path has no SHA. Fetch the current file first only when the write replaces an existing one.

Triaging a failed write

Symptom	Cause	Action
HTTP 409	sha omitted on a path that already exists	Fetch the current SHA, retry as an update
HTTP 422	Stale sha — the file changed between the read and the write	Re-fetch the SHA immediately before the write
403 or 422 with no SHA explanation	Branch protection requires signed commits	Stop and report
HTTP 413	Reverse-proxy body limit in front of Gitea	Report; retrying cannot fix it
Client-side input-validation error naming sha	sha omitted on delete_file, where it is schema-required	Fetch the current SHA and retry — nothing was sent to Gitea
HTTP 404	Wrong path, or a token without write:repository	Verify the path, then the token's scopes

Signed commits. These writes create commits server-side from a bare API token with no 2FA or PGP context. If the target branch's protection rule requires signed commits, Gitea rejects the write as a generic 403 or 422 that never names signing, and reads against that same branch keep succeeding right up until the write. When a write fails without a clean 409 or 404 explanation, check the branch's protection rule before assuming the SHA is wrong and retrying.

Payload size. base64 inflates content roughly 33% over the raw file size, and a 413 is usually a reverse-proxy body-size limit in front of the Gitea instance rather than a Gitea-side rejection. No amount of retrying, or changing the SHA, path, or branch, will fix it — the proxy's config has to be raised, which is outside this skill's control. Surface that distinction instead of retrying the same call.