docs(gitea): recover signed-commit/reverse-proxy gotchas from orphaned commit

Commit 7ad9fb6 (an orphaned parallel gitea-files authoring run, superseded
by 0c7dd04 during a worktree merge race) backfilled two real gotchas into
troubleshooting.md that the winning version didn't carry: protected-branch
signed-commit rejection and reverse-proxy 413 on large file writes, both
sourced from context7:/websites/gitea. Recovering them since they're
genuine findings, not duplicated elsewhere.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

plugins/gitea/docs/research/docs/gitea/sources.md

@@ -24,8 +24,8 @@
 ## context7-websites-gitea
 
 - **URL:** context7:/websites/gitea
-- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions, branch protection and PR review/merge rules, release and webhook semantics, issue/PR automatic cross-reference linking. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout.
-- **Contributing files:** workflow-conventions.md
+- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions, branch protection and PR review/merge rules, release and webhook semantics, issue/PR automatic cross-reference linking, protected-branch signed-commit safeguards, reverse-proxy request size limits, and repository upload limits. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout.
+- **Contributing files:** workflow-conventions.md, troubleshooting.md
 - **Status:** `extracted`
 
 ## context7-gitea-tea-cli

plugins/gitea/docs/research/docs/gitea/troubleshooting.md

@@ -3,6 +3,7 @@ topic: troubleshooting
 source_keys:
   - gitea-mcp-repo
   - gitea-mcp-slim-go
+  - context7-websites-gitea
 ---
 
 # Gitea MCP — Troubleshooting
@@ -86,6 +87,14 @@ The MCP server surfaces HTTP error codes from the Gitea REST API:
 
 The `milestones` parameter on `list_issues` accepts milestone names or IDs as an array. Using IDs is more reliable — milestone names are mutable. Always prefer filtering by milestone ID when programmatically filtering.
 
+## Signed-commit branch protection can silently block file writes
+
+A protected branch can require signed commits as a safeguard (`docs.gitea.com/usage/access-control/protected-branches`). `create_or_update_file` and `delete_file` both create commits server-side via a bare API token call with no 2FA/PGP context — if the target branch's protection rule requires signed commits, Gitea rejects the push outright. The MCP tool surfaces this as a generic write failure (typically 403 or 422), not a message naming "signed commit required" — `get_file_contents` (read) keeps succeeding right up until the write. When a file write fails without a 409 (missing/stale SHA) or 404 (bad path) explanation, check whether the target branch's protection rule requires signed commits before assuming the SHA is wrong.
+
+## Large file content can hit a reverse-proxy 413, not a Gitea limit
+
+`create_or_update_file` sends `content` base64-encoded, which inflates the payload ~33% over the raw file size. A `413 Request Entity Too Large` response is commonly a reverse-proxy body-size limit in front of the Gitea instance (e.g. nginx `client_max_body_size`), not a Gitea-side rejection (`docs.gitea.com/administration/reverse-proxies`, `docs.gitea.com/help/faq`) — Gitea's own configured upload limit is a separate, unrelated setting (50MB per file by default, for the web upload feature). A 413 on a file-write call is an infrastructure-layer symptom that cannot be fixed by changing the request (a different SHA, path, or branch won't help) — it requires the reverse-proxy config to be raised, which is outside the skill's or the calling agent's control. Surface this distinction to the user rather than retrying the same call.
+
 ## `per_page` defaults vary
 
 Not all endpoints share the same default `per_page`: