Defame1297
8680adf4c0
gitea-releases was the weakest skill in the plugin: no allowed-tools, no owner/repo resolution, and a checkbox list where a dispatch table belongs, so an agent reaching it had to guess both its permissions and its inputs. The id-vs-tag_name trap — deleting by tag name where the API wants the numeric id — is restored as an explicit Gotcha because it destroys the wrong release silently. Elsewhere the `exclusive` flag was documented on the wrong side of the read/write split, and label data from one instance was presented as though it were universal, which invites an agent to assume a taxonomy that does not exist on the target repo. rename_branch was missing from the branch surface. Reference prose and fences are cleaned up in passing.
80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
---
|
|
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
|
|
|
|
```text
|
|
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.
|