Gitee Review Comments (Line-level Comments for Files/Documents)
Manage review comments for specific lines of a file in the current branch of a Gitee repository (see "Mechanism Facts" for commit carrier and hiding rules). Review comments are stored on the Gitee server, do not enter git objects, and have zero impact on git itself.
This skill only handles the "review comment" domain (create, read, update, delete, reply). It does NOT handle PR/Issue operations — that is the responsibility of Gitee's official MCP.
Mechanism Facts
Commit is hidden from users: The commits mentioned below are only underlying implementation carriers. When communicating with users, only mention "file: line range" and do not use the terms sha/commit. The carrier commit is automatically selected by the skill (default to the latest commit of the current branch), and users are unaware of it.
- Comments must be attached to a commit: The creation endpoint is
POST /repos/{owner}/{repo}/commits/{sha}/comments
, where is a required path parameter; the annotations for GET /repos/{owner}/{repo}/comments
and its management endpoint are both "Commit Comments". There are no independent repository comments that are not attached to a commit.
- Gitee does not support true line anchoring: Although the official documentation lists (relative file path) + (Diff relative line number) for , the server silently ignores these two parameters in practice — the response after POST only contains
id/body/user/source/target(issue:null,pull:null)/timestamp
, with no line/file fields. That means you cannot anchor comments to specific lines of a file like GitHub/GitLab does.
- Positioning can only rely on the text convention in the body: For example,
location: docs/L1/USER-STORY.md:55-69
. This is why this skill writes "file: line range" into the body.
When to Use
- Need to programmatically record review opinions when reviewing any file in the project (Markdown documents, code, PNG images, configuration files, etc.)
- Need to locate review opinions by "file: line range" (Gitee has no line anchoring, see "Mechanism Facts", positioning relies on the text in the body)
- Need to query all unresolved review opinions (to-do list)
- Need to reply to a colleague's or another Agent's review opinion (in the comment section, not private chat)
- Need to mark a review opinion as [Resolved] or delete it (deletion equals resolution, clearing completes the current review cycle)
CLI Availability (No Pre-check, Prompt Installation Only on Failure)
By default, directly execute the
command (already installed in most cases).
Do NOT pre-check with
every time — that wastes tokens. Only follow the exit code for downgrade/prompt when execution
fails:
| Execution Result / Exit Code | Scenario | Handling |
|---|
| Exit code 0 | Success | Return the result directly |
| / Exit code 127 | CLI not installed | Stop and prompt the user to manually install + log in, then continue (see below) |
| Exit code 5 / Authentication Error | Not logged in or invalid credentials | Prompt the user to run first |
Prompt when CLI is not installed (let the user execute it themselves, do NOT install on their behalf):
bash
npm install -g @gitee/gitee-cli
gitee auth login
This skill
does NOT install for you or handle any token/credentials. Authentication is handled by the login credentials from
, and
automatically reads
~/.config/gitee/credentials.yml
when called.
Re-entry Semantics: After a failure caused by missing CLI, once the user installs and logs in, re-calling this skill will automatically proceed without modifying the skill.
Parameter Parsing Rules
| Parameter | Default Source | Description |
|---|
| Derived only from the current repository's origin: Parsed from git remote get-url origin
(e.g., git@gitee.com:syllr/enterprise-ai-hub.git
→ ), and the host must be | Perceivable by users (repository); must be a Gitee repository |
| Carrier commit, automatically selected, user-unaware. See the "Carrier Commit Decision Chain" below — default to the latest remote sha of the current branch (git ls-remote origin refs/heads/<branch>
), fallback to gitee api branches/<branch>
| Internal carrier, not exposed to users; only provided to AI for debugging/management |
Parse
and verify if it is a Gitee repository:
bash
# Derive only from origin + verify host == gitee.com (this skill only operates on current Gitee repository comments)
url=$(git remote get-url origin)
host=$(echo "$url" | sed -E 's#(https?|ssh|git)://##; s#git@##; s#[:/].*##')
repo=$(echo "$url" | sed -E 's#.*[:/]([^/]+)/([^/.]+)(\.git)?$#\1/\2#')
[ "$host" != "gitee.com" ] && echo "Current repository is not a Gitee repository (remote host = $host). This skill can only operate on Gitee repository comments, process terminated." && exit 1
Target comment repository = origin of the current git repository, and must be
. If not Gitee → prompt and terminate (do not operate on non-Gitee repositories).
Carrier Commit Decision Chain (For AI; Hidden from Users)
Comments must be attached to a commit (commit is hidden from users, see "Mechanism Facts"). Users only provide "branch (optional) + location", and the carrier sha is automatically selected by AI following this chain, without exposing sha/commit terms to users. The branch name is also used for the
annotation in the body.
Step 1 Determine Branch Name (Perceivable by Users):
- User explicitly specifies → use it
- Otherwise
git branch --show-current
(locally checked-out branch)
- If empty (detached/CI) → CI environment variable
${GIT_BRANCH:-${CI_COMMIT_REF_NAME:-${GITHUB_REF#refs/heads/}}}
- Still empty →
git ls-remote --symref origin HEAD
to get the remote default branch
- All empty → Ask the user to specify a branch (the only point requiring user input)
Step 2 Obtain Carrier sha (Guaranteed to Exist on Gitee Server, Read-only):
bash
# Preferred: Latest remote commit of current branch (read-only, no login required, reliable even with shallow clone)
sha=$(git ls-remote origin "refs/heads/$branch" | awk '{print $1}')
# If local branch name != remote name, try upstream name
[ -z "$sha" ] && { up=$(git rev-parse --abbrev-ref @{u} | sed 's#^origin/##'); [ -n "$up" ] && sha=$(git ls-remote origin "refs/heads/$up" | awk '{print $1}'); }
# Official API fallback (confirm branch exists + get latest sha)
[ -z "$sha" ] && sha=$(gitee api -p "/repos/$repo/branches/$branch" | python3 -c 'import json,sys; print(json.load(sys.stdin)["commit"]["sha"])')
[ -z "$sha" ] && { echo "Branch $branch does not exist or has no commits, please check the branch name"; exit 1; }
Key Points for Carrier Commit:
- Do not fixate on main — use
git branch --show-current
to get the current branch during team branch reviews, otherwise comments will be attached to the latest commit of the wrong branch.
- Do not deliberately find the "last commit that modified the target file" — Gitee silently ignores /, positioning relies on the text in the body, so which commit it is attached to does not affect correctness; attaching to the latest commit of the current branch has the best visibility on the web page.
- Local is not used as default — local commits may not have been pushed, and POST will return 404 (prompt the user to push or confirm the branch name in this case).
Comment Format Convention (Fixed Format, All Comments Must Follow)
Body Template (Standard Review Comment)
markdown
[Pending] branch: <branch name> · location: <file>:<line range>
> <One line of original text>
<Opinion content>
@<Person to reply>
in the template are
placeholders (replace when filling); see the "Field Quick Reference" below for the required status/description of each field,
do not copy placeholders or bracket descriptions into the body.
Field Quick Reference (Fixed Position, Do Not Reorder)
| Field | Position | Required | Description |
|---|
| Status | Start of first line | ✅ | (default) / ; means modifying this prefix |
| Branch | First line | ✅ | ; default to current branch (git branch --show-current
), automatically added if not specified by user |
| location | First line | ✅ | location: <file>:<line range>
; relative to project root path, can point to any file type; line numbers can be omitted if not found |
| Original Text Extract | Blockquote below first line | Recommended | > <One line of original text>
, helps readers locate; better to write it |
| Opinion Content | Main body | ✅ | Main content of review opinion, can be multi-line |
| @ Someone | End of body | Optional | , colleague who needs to reply |
The first line is the
meta-information line:
[Status] branch: branch · location: file:line range
, separated by
in fixed order (Status → branch → location).
/parsing extracts branch, location, and status from this line.
Reply Comment Format
markdown
Re: <ID of comment being replied to>
<Reply content>
- Replies are attached to the same commit, with the first line of the body being
Re: <ID of comment being replied to>
.
Resolution Methods
- Preferred PATCH (No Permission Threshold):
- First use
GET /repos/{owner}/{repo}/comments/{id}
to get the original body
- Construct a new body: change the prefix in the first line to , keep the rest of the content unchanged
- Submit the PATCH:
bash
gitee api -X PATCH -f "body=[Resolved]<Original body without the first line's [Pending]>" \
"/repos/{owner}/{repo}/comments/{id}"
Or DELETE (Deletion Equals Resolution, Requires Permission):
bash
gitee api -X DELETE "/repos/{owner}/{repo}/comments/{id}"
Location Positioning Rules (AI Actively Locates When User Does Not Provide File/Lines)
must be relative to the current project root path (e.g.,
,
,
),
do not add repository name/absolute path; can point to any file type,
images (PNG, etc.) can also be directly used as comment targets (
location: assets/diagram.png
).
- Prioritize using the "file: line range" (or file path) provided by the user; write it directly into if provided.
- If user does not provide file/lines → AI actively locates without forcing a question: use /context (based on evaluation topic, keywords, file name, chapter) to find the corresponding file; include line numbers if easy to find (
location: file:line range
).
- If line numbers cannot be found or span multiple locations (semantic uncertainty, affecting multiple positions) → at least includes the file path, line range can be omitted (
location: docs/L1/USER-STORY.md
). Do not get stuck/abandon comments due to lack of precise line numbers.
- Priority: File must be found (ask user only if not found); line numbers are best-effort, leave at file level if not found.
Atomic Operations (Via )
Substitute
and
in all commands according to the parameter parsing rules above.
Body Quotation Rules: Use
single quotes to wrap the body if it contains Chinese; use
double quotes to expand when it contains shell variables (e.g.,
); if the content contains single quotes or multiple lines, use
to read from a file instead.
1. list —— Query All Repository Comments (= Unresolved To-do List)
bash
gitee api -p "/repos/{owner}/{repo}/comments"
This endpoint
does not return commit information attached to comments. Use
to filter by commit. The output is JSON, which needs to be parsed into a table.
Output Table Columns:
id / Branch (extracted from body) / Location (extracted from body) / Status ([Pending]/[Resolved]) / Author / Timestamp
Parsing Key Points (Extracted from Body):
- : Extract the content after the colon from the line in the body containing
location: <path>:<line range>
- : Extract the content after the colon from the line in the body containing ; mark comments without in old versions as "Unmarked"
- Status: If the first line of the body starts with → Resolved; otherwise ([Pending] or no status marked) → Pending
2. add —— Submit a Review Comment for "File: Line Range"
Semantics: Submit a review comment for specific lines of a file in the current branch of the current repository. The carrier commit is automatically selected (default to the latest commit of the current branch), user-unaware.
bash
gitee api -X POST -f 'body=<body content>' \
"/repos/{owner}/{repo}/commits/{sha}/comments"
The response contains
(ID of the new comment, used for subsequent resolve/reply operations).
3. reply —— Reply to a Comment Thread
Construct the body according to the "Reply Comment Format" (first line
, then reply content on a new line), use
to pass multi-line content:
bash
gitee api -X POST --body "Re: {id}
<Reply content>" \
"/repos/{owner}/{repo}/commits/{sha}/comments"
Replies are attached to the
same commit, with the first line of the body being
Re: <ID of comment being replied to>
(see "Reply Comment Format" for details).
4. resolve —— Resolve a Comment
Preferred PATCH (No Permission Threshold):
- First use
GET /repos/{owner}/{repo}/comments/{id}
to get the original body
- Construct a new body: change the prefix in the first line to , keep the rest of the content unchanged
- Submit the PATCH:
bash
gitee api -X PATCH -f "body=[Resolved]<Original body without the first line's [Pending]>" \
"/repos/{owner}/{repo}/comments/{id}"
Or DELETE (Deletion Equals Resolution, Requires Permission):
bash
gitee api -X DELETE "/repos/{owner}/{repo}/comments/{id}"
5. show-commit —— Query All Comments Attached to a Commit
bash
gitee api -p "/repos/{owner}/{repo}/commits/{sha}/comments"
One Review Cycle Process
add (record review opinions, including location + original text extract)
→ list (summarize to-dos, provide to user/other Agent)
→ reply (other party's response) or resolve (mark as [Resolved] after processing)
→ list (empty list = current review cycle completed)
Error Handling and Permission Boundaries
| Scenario | Handling |
|---|
| CLI does not exist | Output npm install -g @gitee/gitee-cli
+ , stop and wait |
| Failed to delete others' comments (ordinary members can only delete their own) | Downgrade to PATCH [Resolved] and prompt the user "No permission to delete, marked as resolved" |
| Not logged in / invalid credentials | Prompt the user to execute first |
| Quotation conflict caused by single quotes in body | Use to read from a file instead |
| 404 (comment does not exist / no permission) | Output the error as is, check and |
Examples
Record a review comment (automatically selects the latest commit of the current branch as carrier, user-unaware):
bash
repo=$(git remote get-url origin | sed -E 's#.*[:/]([^/]+)/([^/.]+)(\.git)?$#\1/\2#')
branch=$(git branch --show-current) # Current branch (perceivable by user; can also be specified via --branch)
sha=$(git ls-remote origin "refs/heads/$branch" | awk '{print $1}') # Remote carrier sha, user-unaware
body='[Pending] branch: '"$branch"' · location: docs/L1/USER-STORY.md:55-69
> Summarize all stories in one table, allowing readers to see "what user stories there are" in 30 seconds. Organize by role.
The repeated "(DOMAIN-MODEL §3)" at the end of each line in L61-L69 can be moved to the header description once'
gitee api -X POST -f "body=$body" "/repos/$repo/commits/$sha/comments"
List unresolved to-do list:
bash
gitee api -p "/repos/{owner}/{repo}/comments"
Parse the returned JSON into a table with columns
id / Branch / Location / Status / Author / Timestamp
, and only mark [Pending] items.
Resolve a comment (PATCH to add [Resolved]):
bash
# First copy the original body, remove [Pending], change the prefix to [Resolved], then submit
gitee api -X PATCH -f 'body=[Resolved]...' "/repos/{owner}/{repo}/comments/{id}"