Gitea PR Plugin

Gives the agent per-user Gitea pull-request tools — read PR details, diffs, and comments in chat, and (behind approval) post review comments and submit reviews on Gitea. Like Redmine, it authenticates as the calling user: each tool reads the user's personal Gitea access token from User Secrets at call time. There is no shared instance token.

Load user_secrets alongside this plugin.

Tools

Tool	Approval	Purpose
`gitea_list_prs`	none (read)	List open/recent PRs for a repo.
`gitea_get_pr`	none (read)	Fetch one PR's details (title, body, state, author).
`gitea_get_pr_diff`	none (read)	Get the unified diff (truncated past `max_pr_diff_bytes`).
`gitea_get_pr_files`	none (read)	List changed files with patch hunks — the preferred entry point for large PRs.
`gitea_get_pr_commits`	none (read)	List commits in the PR.
`gitea_get_pr_comments`	none (read)	Read existing discussion comments.
`gitea_post_pr_comment`	`gitea.post_pr_comment`	Post a general (thread-level) PR comment.
`gitea_post_line_comment`	`gitea.post_line_comment`	Post a line-level review comment on a specific file/line.
`gitea_submit_review`	`gitea.submit_review`	Submit an overall review verdict (comment / approve / request changes).

Write tools ask for approval before a comment or verdict lands on Gitea.

Who gets which half

Two gates, not one. target_agents (default all) decides whether the family is offered at all; write_target_agents (default main) then decides who gets the three write tools.

By default a subagent can fetch a PR and its diff but cannot comment or submit a verdict. Set write_target_agents: all if subagents should also write.

Ask the assistant to ground claims in actual diff lines (gitea_get_pr_diff / gitea_get_pr_files) and to cross-reference the ingested codebase.

Two review triggers

Chat-initiated (always on). Type "review PR #42" in a normal turn; write tools hit the interactive approval dialog. Nothing extra to configure.
Headless /review webhook (off by default). A developer comments /review on a Gitea PR (or, when this path is enabled, a PR is opened, reopened, or synchronized) → Gitea POSTs to /ops/webhook/gitea-pr (authenticated by the same Gitea HMAC the push webhook uses, over config.webhooks.secrets) → a headless review turn. Because there is no human at an approval dialog, this path is gated behind auto_post_on_review_comment (default false) and, when enabled, only auto-runs the comment tools in auto_runnable_write_tools — never gitea_submit_review, merge, or close.

A posted-comment ledger tracks findings already posted on a PR so a re-review (for example after a later push) does not repeat comments.

Configuration

plugins:
  - module: codumentor.plugins.gitea_pr
    class: GiteaPRPlugin
    args:
      enabled: true
      base_url: "https://gitea.example.com"   # optional; falls back to config.auth.gitea.base_url
      api_token_secret: gitea_api_token       # per-user secret name (default)
      default_repo: "owner/repo"              # optional; lets "PR #42" resolve
      target_agents: all                      # main | subagent | all — the whole family
      write_target_agents: main               # same values, write tools only
      # Headless /review webhook — off by default
      auto_post_on_review_comment: false
      review_owner_user_id: "gitea-bot"       # service account for headless turns
      # auto_runnable_write_tools defaults to the two comment tools

base_url is required only when enabled: true and neither args.base_url nor config.auth.gitea.base_url is set.

Parameters

Option	Type	Default	Description
`base_url`	`string`	`config.auth.gitea.base_url`	Base URL of the Gitea instance.
`api_token_secret`	`string`	`gitea_api_token`	Per-user secret name holding the personal access token.
`default_repo`	`string`	(none)	`owner/repo` used when a call omits the repository.
`max_pr_diff_bytes`	`int`	`400000`	Truncate diffs larger than this.
`request_timeout_s`	`float`	`30.0`	Per-request timeout in seconds.
`target_agents`	`string`	`all`	`main` \
`write_target_agents`	`string`	`main`	Same values, applied to the write tools only. Subagents keep the read half.
`auto_post_on_review_comment`	`bool`	`false`	Spawn a headless turn from a `/review` webhook comment (and from PR opened / reopened / synchronize events).
`auto_runnable_write_tools`	`list[string]`	`[gitea_post_line_comment, gitea_post_pr_comment]`	The only write tools a headless review may auto-run.
`review_owner_user_id`	`string`	(none)	Codumentor user id the headless turn runs as. Required when `auto_post_on_review_comment` is `true`.

Enabling the webhook also requires the shared webhooks: block (the same HMAC secret store the push webhook uses):

webhooks:
  enabled: true
  secrets:
    - "${CODUMENTOR_WEBHOOK_SECRET}"

Point Gitea at POST {api.external_url}/ops/webhook/gitea-pr with that secret. The endpoint authenticates every event even when auto_post_on_review_comment is off, so you can enable headless review later without reconfiguring Gitea.

Per-user setup

Each user adds their personal Gitea access token as a secret:

In Gitea: Settings → Applications → Generate New Token (read repository scope for PR reads; add write issue/PR scope to post comments).
In Codumentor: Settings → Extensions → User Secrets → Add, name it gitea_api_token (or whatever api_token_secret is set to), paste the token.

The User Secrets pane shows "Gitea API token — needed by Gitea PR" with set/unset state. When a tool runs without the secret set, it returns a clear, non-retryable message telling the user to add it — no network call is made.

Notes

All tools act as the calling user via their personal token — there is no shared instance-level Gitea credential.
gitea_get_pr_files is the preferred entry point for large PRs; gitea_get_pr_diff truncates at max_pr_diff_bytes.
Headless reviews run as review_owner_user_id, using that account's token to post comments.