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.
3.8 KiB
source_keys
| source_keys | ||
|---|---|---|
|
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
get_file_contents(owner, repo, ref: <branch>, path)→ read the top-levelsha.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.
get_file_contents(owner, repo, ref: <branch>, path)→ read the top-levelsha.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.