Defame1297
bbc73008a3
Generated output, not authored content: scripts/sync-plugin-content.sh --all. Claude Code has no .apm/ awareness, so this compiled mirror must track .apm/ or the check-plugin-content-sync pre-push hook reports drift. Deferred to a single commit at the end of the wave on purpose. sync_dir runs rm -rf before every copy, so running it while seven agents were editing the same plugin would have raced them; agents were told not to sync for that reason. Refs #99
3.3 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 — delete_file without sha returns
HTTP 422.
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 | sha missing or stale |
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 |
| 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.