Defame1297
8a154dacbe
An independent clean-context audit of the newly-authored gitea-prs skill flagged that old_line_num/new_line_num (write path, pull_request_review_write create) and position/old_position (read path, get_review_comments) name the same concept differently — the same class of write/read field mismatch that produced the review_scomments typo elsewhere in this domain. Adds one clarifying sentence to references/reviews.md so an agent skimming only one side doesn't assume symmetric field names.
44 lines
3.9 KiB
Markdown
44 lines
3.9 KiB
Markdown
---
|
|
topic: reviews
|
|
source_keys:
|
|
- gitea-mcp-repo
|
|
- gitea-mcp-slim-go
|
|
---
|
|
|
|
# PR review execution detail
|
|
|
|
Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schema, not copied from the plugin's research doc verbatim — same sourcing discipline as `references/pull-requests.md`.
|
|
|
|
## Review state machine
|
|
|
|
A review is not a single write. It moves through states:
|
|
|
|
1. **`create`** — opens a review in `"PENDING"` state, optionally attaching inline comments. Nothing is visible to other users yet.
|
|
2. **`submit`** — finalizes the pending review with a terminal `state`: `"APPROVED"`, `"REQUEST_CHANGES"`, or `"COMMENT"`. This is the point at which the review becomes visible and counts toward merge-gate requirements (see `references/merging.md`).
|
|
3. **`dismiss`** — invalidates an already-submitted review (e.g. an approval that's no longer valid after force-push), with an optional `message` giving the reason. Dismissal does not delete the review record — it stays visible but marked dismissed.
|
|
4. **`delete`** — removes a review outright. Use only for a review that was never submitted (e.g. abandoning a `PENDING` draft); do not use `delete` to retract a submitted review — use `dismiss` instead.
|
|
|
|
## `pull_request_review_write`
|
|
|
|
**Parameters:**
|
|
- `method` (string, required) — `"create"` | `"submit"` | `"delete"` | `"dismiss"`
|
|
- `owner` (string, required)
|
|
- `repo` (string, required)
|
|
- `pull_number` (number, required)
|
|
- `review_id` (number, required for every method except `"create"`, which returns the ID to use for the follow-up `submit`/`delete`/`dismiss` call)
|
|
- `state` (string, optional) — `"APPROVED"` | `"REQUEST_CHANGES"` | `"COMMENT"` | `"PENDING"` — set on `"create"` (typically `"PENDING"`, or a terminal state to create-and-submit in one call if the server supports it) or `"submit"` (terminal state)
|
|
- `body` (string, optional) — overall review comment text
|
|
- `commit_id` (string, optional, for `"create"`) — anchors inline comments to a specific commit SHA (typically the PR's current head SHA from `pull_request_read method: "get"`)
|
|
- `message` (string, optional, for `"dismiss"`) — dismissal reason
|
|
- `comments` (array of objects, optional, for `"create"`) — inline comments, each: `{path, body, old_line_num, new_line_num}` — `path` is the file path, `body` is the comment text, `new_line_num` anchors to a line in the new (added) side of the diff, `old_line_num` anchors to a line in the old (removed) side; use whichever side the comment applies to, not both
|
|
|
|
## Reading reviews (`pull_request_read`)
|
|
|
|
- `method: "get_reviews"` — array of review summaries: `id`, `state`, `body`, `user` (login), `comments_count`, `submitted_at`, `html_url`, `stale` (bool — the PR was pushed to after this review was submitted, meaning it may be outdated), `official` (bool), `dismissed` (bool).
|
|
- `method: "get_review"` (requires `review_id`) — single review detail.
|
|
- `method: "get_review_comments"` (requires `review_id`) — array of inline comments: `id`, `body`, `path`, `position`, `old_position`, `diff_hunk`, `user`, `html_url`, `created_at`, `updated_at`.
|
|
|
|
**`review_scomments` typo:** the full PR object returned by `pull_request_read method: "get"` includes a field named `review_scomments` (a count), not `review_comments` — a source-level misspelling in gitea-mcp v1.3.0's `slim.go`. Do not write code or instructions that reference `review_comments` on that response; it will always be `undefined`. This is distinct from the `get_review_comments` method above, which is spelled correctly and returns the actual comment objects.
|
|
|
|
**Inline-comment field names differ between write and read.** The `comments` array on `pull_request_review_write method: "create"` uses `old_line_num`/`new_line_num`. The `get_review_comments` read response uses different field names for the same concept — `position` (new-side line) and `old_position` (old-side line). Do not assume the same key names apply on both sides of the round trip.
|