From 22d15cf73408a661045b85bcc29bc6c8cd6182b1 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 5 Jul 2026 10:49:51 +0000 Subject: [PATCH] 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 --- plugins/gitea/docs/research/docs/gitea/sources.md | 4 ++-- .../gitea/docs/research/docs/gitea/troubleshooting.md | 9 +++++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/plugins/gitea/docs/research/docs/gitea/sources.md b/plugins/gitea/docs/research/docs/gitea/sources.md index 2abbf0d..aee54f1 100644 --- a/plugins/gitea/docs/research/docs/gitea/sources.md +++ b/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 diff --git a/plugins/gitea/docs/research/docs/gitea/troubleshooting.md b/plugins/gitea/docs/research/docs/gitea/troubleshooting.md index 5ad1632..fb94da9 100644 --- a/plugins/gitea/docs/research/docs/gitea/troubleshooting.md +++ b/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`: