Back to Details

gitlab-discussion

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Discussion Skill

GitLab讨论管理技能

Threaded discussion management for GitLab using 
glab api
raw endpoint calls.
通过
glab api
原生端点调用实现GitLab的线程式讨论管理。

Quick Reference

快速参考

OperationCommand PatternRisk
List MR discussions
glab api projects/:id/merge_requests/:iid/discussions
-
List issue discussions
glab api projects/:id/issues/:iid/discussions
-
Get discussion
glab api projects/:id/merge_requests/:iid/discussions/:id
-
Create discussion
glab api projects/:id/merge_requests/:iid/discussions -X POST -f ...
⚠️
Reply to discussion
glab api projects/:id/.../discussions/:id/notes -X POST -f ...
⚠️
Resolve discussion
glab api projects/:id/.../discussions/:id -X PUT -f resolved=true
⚠️
Delete note
glab api projects/:id/.../discussions/:id/notes/:nid -X DELETE
⚠️⚠️
Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger
操作命令模式风险
列出合并请求讨论
glab api projects/:id/merge_requests/:iid/discussions
-
列出议题讨论
glab api projects/:id/issues/:iid/discussions
-
获取讨论详情
glab api projects/:id/merge_requests/:iid/discussions/:id
-
创建讨论
glab api projects/:id/merge_requests/:iid/discussions -X POST -f ...
⚠️
回复讨论
glab api projects/:id/.../discussions/:id/notes -X POST -f ...
⚠️
标记讨论为已解决
glab api projects/:id/.../discussions/:id -X PUT -f resolved=true
⚠️
删除评论
glab api projects/:id/.../discussions/:id/notes/:nid -X DELETE
⚠️⚠️
风险说明: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

适用场景

ALWAYS use when:
  • User mentions "discussion", "thread", "conversation"
  • User wants to add code review comments
  • User mentions "resolve", "unresolve" discussions
  • User wants to reply to existing comments/threads
  • User wants line-specific comments on MRs
NEVER use when:
  • User wants simple notes/comments (use 
    glab mr note
    or 
    glab issue note
    )
  • User wants to review MR changes (use gitlab-mr)
  • User wants to search comments (use gitlab-search with 
    notes
    scope)
务必在以下场景使用：
  • 用户提及"讨论"、"线程"、"对话"
  • 用户想要添加代码评审评论
  • 用户提及"标记已解决"、"取消标记已解决"讨论
  • 用户想要回复现有评论/线程
  • 用户想要在合并请求中添加特定行的评论
请勿在以下场景使用：
  • 用户想要添加简单的笔记/评论（使用
    glab mr note
    或
    glab issue note
    ）
  • 用户想要评审合并请求的变更（使用gitlab-mr）
  • 用户想要搜索评论（使用gitlab-search并指定
    notes
    范围）

API Prerequisites

API前置条件

Required Token Scopes: 
api
Permissions:
  • Read discussions: Reporter+ (for private repos)
  • Create discussions: Reporter+
  • Resolve discussions: Developer+ (or MR author)
所需Token权限范围： 
api
权限要求：
  • 读取讨论：报告者及以上权限（私有仓库）
  • 创建讨论：报告者及以上权限
  • 标记讨论为已解决：开发者及以上权限（或合并请求作者）

Available Commands

可用命令

List MR Discussions

列出合并请求讨论

bash
undefined
bash
undefined

List all discussions on MR

列出合并请求的所有讨论

glab api projects/123/merge_requests/1/discussions --method GET
glab api projects/123/merge_requests/1/discussions --method GET

With pagination

分页查询

glab api projects/123/merge_requests/1/discussions --paginate
glab api projects/123/merge_requests/1/discussions --paginate

Using project path

使用项目路径

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/merge_requests/1/discussions"
undefined
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/merge_requests/1/discussions"
undefined

List Issue Discussions

列出议题讨论

bash
undefined
bash
undefined

List all discussions on issue

列出议题的所有讨论

glab api projects/123/issues/42/discussions --method GET
glab api projects/123/issues/42/discussions --method GET

With pagination

分页查询

glab api projects/123/issues/42/discussions --paginate
undefined
glab api projects/123/issues/42/discussions --paginate
undefined

Get Specific Discussion

获取特定讨论详情

bash
undefined
bash
undefined

Get MR discussion by ID

获取合并请求的指定讨论详情

glab api projects/123/merge_requests/1/discussions/abc123 --method GET
glab api projects/123/merge_requests/1/discussions/abc123 --method GET

Get issue discussion by ID

获取议题的指定讨论详情

glab api projects/123/issues/42/discussions/def456 --method GET
undefined
glab api projects/123/issues/42/discussions/def456 --method GET
undefined

Create Discussion on MR

在合并请求中创建讨论

bash
undefined
bash
undefined

Create general discussion

创建普通讨论

glab api projects/123/merge_requests/1/discussions --method POST
-f body="This looks good overall, but I have some suggestions."
glab api projects/123/merge_requests/1/discussions --method POST
-f body="整体看起来不错，但我有一些建议。"

Create discussion on specific line (diff note)

在特定行创建讨论（差异评论）

glab api projects/123/merge_requests/1/discussions --method POST
-f body="This could be simplified using a helper function."
-f position[base_sha]="abc123"
-f position[head_sha]="def456"
-f position[start_sha]="abc123"
-f position[position_type]="text"
-f position[new_path]="src/app.py"
-f position[new_line]=42
glab api projects/123/merge_requests/1/discussions --method POST
-f body="这里可以用辅助函数简化。"
-f position[base_sha]="abc123"
-f position[head_sha]="def456"
-f position[start_sha]="abc123"
-f position[position_type]="text"
-f position[new_path]="src/app.py"
-f position[new_line]=42

Create discussion on old line (removed code)

在已删除代码的行创建讨论

glab api projects/123/merge_requests/1/discussions --method POST
-f body="Why was this removed?"
-f position[base_sha]="abc123"
-f position[head_sha]="def456"
-f position[start_sha]="abc123"
-f position[position_type]="text"
-f position[old_path]="src/old.py"
-f position[old_line]=15
glab api projects/123/merge_requests/1/discussions --method POST
-f body="为什么这段代码被删除了？"
-f position[base_sha]="abc123"
-f position[head_sha]="def456"
-f position[start_sha]="abc123"
-f position[position_type]="text"
-f position[old_path]="src/old.py"
-f position[old_line]=15

Create suggestion

创建代码建议

glab api projects/123/merge_requests/1/discussions --method POST
-f body='```suggestion def improved_function(): return "better implementation"
undefined
glab api projects/123/merge_requests/1/discussions --method POST
-f body='```suggestion def improved_function(): return "better implementation"
undefined

Create Discussion on Issue

在议题中创建讨论

bash
undefined
bash
undefined

Create discussion

创建讨论

glab api projects/123/issues/42/discussions --method POST
-f body="I think we should reconsider this approach."
undefined
glab api projects/123/issues/42/discussions --method POST
-f body="我认为我们应该重新考虑这个方案。"
undefined

Reply to Discussion

回复讨论

bash
undefined
bash
undefined

Reply to MR discussion

回复合并请求的讨论

glab api projects/123/merge_requests/1/discussions/abc123/notes --method POST
-f body="Good point, I'll fix this."
glab api projects/123/merge_requests/1/discussions/abc123/notes --method POST
-f body="说得对，我会修复这个问题。"

Reply to issue discussion

回复议题的讨论

glab api projects/123/issues/42/discussions/def456/notes --method POST
-f body="I agree with the above."
undefined
glab api projects/123/issues/42/discussions/def456/notes --method POST
-f body="我同意上述观点。"
undefined

Resolve/Unresolve Discussion

标记/取消标记讨论为已解决

bash
undefined
bash
undefined

Resolve MR discussion

标记合并请求的讨论为已解决

glab api projects/123/merge_requests/1/discussions/abc123 --method PUT
-f resolved=true
glab api projects/123/merge_requests/1/discussions/abc123 --method PUT
-f resolved=true

Unresolve MR discussion

取消标记合并请求的讨论为已解决

glab api projects/123/merge_requests/1/discussions/abc123 --method PUT
-f resolved=false
undefined
glab api projects/123/merge_requests/1/discussions/abc123 --method PUT
-f resolved=false
undefined

Update Note

更新评论

bash
undefined
bash
undefined

Update note in discussion

更新讨论中的评论

glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method PUT
-f body="Updated comment text"
undefined
glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method PUT
-f body="更新后的评论内容"
undefined

Delete Note

删除评论

bash
undefined
bash
undefined

Delete note from discussion

删除讨论中的评论

glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method DELETE
undefined
glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method DELETE
undefined

Position Object for Diff Notes

差异评论的位置对象

For line-specific comments on MRs, you need to provide position information:
FieldRequiredDescription
base_sha
YesSHA of the base commit (target branch)
head_sha
YesSHA of the head commit (source branch)
start_sha
YesSHA of the start commit
position_type
Yes
text
for code, 
image
for images
new_path
For new/modifiedPath in new version
new_line
For new/modifiedLine number in new version
old_path
For deletedPath in old version
old_line
For deletedLine number in old version
在合并请求中添加特定行的评论时，需要提供位置信息：
字段是否必填描述
base_sha
是基准提交的SHA（目标分支）
head_sha
是头部提交的SHA（源分支）
start_sha
是起始提交的SHA
position_type
是代码评论填
text
，图片评论填
image
new_path
新增/修改文件时必填新版本中的文件路径
new_line
新增/修改文件时必填新版本中的行号
old_path
删除文件时必填旧版本中的文件路径
old_line
删除文件时必填旧版本中的行号

Get SHAs for Position

获取位置信息所需的SHA

bash
undefined
bash
undefined

Get MR details to find SHAs

获取合并请求详情以获取SHA

mr_info=$(glab api projects/123/merge_requests/1) base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha') head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha') start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')
echo "Base: $base_sha" echo "Head: $head_sha" echo "Start: $start_sha"
undefined
mr_info=$(glab api projects/123/merge_requests/1) base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha') head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha') start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')
echo "基准SHA: $base_sha" echo "头部SHA: $head_sha" echo "起始SHA: $start_sha"
undefined

Common Workflows

常见工作流

Workflow 1: Review MR with Comments

工作流1：带评论的合并请求评审

bash
project_id=123
mr_iid=1
bash
project_id=123
mr_iid=1

Get diff refs

获取差异引用信息

mr_info=$(glab api projects/$project_id/merge_requests/$mr_iid) base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha') head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha') start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')
mr_info=$(glab api projects/$project_id/merge_requests/$mr_iid) base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha') head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha') start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')

Add comment on line 42 of new file

在新文件的第42行添加评论

glab api projects/$project_id/merge_requests/$mr_iid/discussions --method POST
-f body="Consider adding error handling here."
-f position[base_sha]="$base_sha"
-f position[head_sha]="$head_sha"
-f position[start_sha]="$start_sha"
-f position[position_type]="text"
-f position[new_path]="src/handler.py"
-f position[new_line]=42
undefined
glab api projects/$project_id/merge_requests/$mr_iid/discussions --method POST
-f body="考虑在这里添加错误处理。"
-f position[base_sha]="$base_sha"
-f position[head_sha]="$head_sha"
-f position[start_sha]="$start_sha"
-f position[position_type]="text"
-f position[new_path]="src/handler.py"
-f position[new_line]=42
undefined

Workflow 2: Resolve All Discussions

工作流2：标记所有讨论为已解决

bash
undefined
bash
undefined

Get all unresolved discussions

获取所有未解决的讨论

glab api projects/123/merge_requests/1/discussions --paginate |
jq -r '.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | .id' |
while read discussion_id; do echo "Resolving: $discussion_id" glab api projects/123/merge_requests/1/discussions/$discussion_id --method PUT
-f resolved=true done
undefined
glab api projects/123/merge_requests/1/discussions --paginate |
jq -r '.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | .id' |
while read discussion_id; do echo "标记为已解决: $discussion_id" glab api projects/123/merge_requests/1/discussions/$discussion_id --method PUT
-f resolved=true done
undefined

Workflow 3: List Unresolved Discussions

工作流3：列出未解决的讨论

bash
undefined
bash
undefined

Show unresolved discussions with content

显示未解决的讨论及内容

glab api projects/123/merge_requests/1/discussions --paginate |
jq -r '.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | "[(.id)] (.notes[0].author.username): (.notes[0].body | split("\n")[0])"'
undefined
glab api projects/123/merge_requests/1/discussions --paginate |
jq -r '.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | "[(.id)] (.notes[0].author.username): (.notes[0].body | split("\n")[0])"'
undefined

Workflow 4: Add Suggestion

工作流4：添加代码建议

bash
project_id=123
mr_iid=1

mr_info=$(glab api projects/$project_id/merge_requests/$mr_iid)
base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha')
head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha')
start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')
bash
project_id=123
mr_iid=1

mr_info=$(glab api projects/$project_id/merge_requests/$mr_iid)
base_sha=$(echo "$mr_info" | jq -r '.diff_refs.base_sha')
head_sha=$(echo "$mr_info" | jq -r '.diff_refs.head_sha')
start_sha=$(echo "$mr_info" | jq -r '.diff_refs.start_sha')

Create suggestion (multi-line needs proper escaping)

创建代码建议（多行内容需要正确转义）

glab api projects/$project_id/merge_requests/$mr_iid/discussions --method POST
-f body='```suggestion const result = await fetchData(); return result.data;
  -f position[base_sha]="$base_sha" \
  -f position[head_sha]="$head_sha" \
  -f position[start_sha]="$start_sha" \
  -f position[position_type]="text" \
  -f position[new_path]="src/api.js" \
  -f position[new_line]=25
glab api projects/$project_id/merge_requests/$mr_iid/discussions --method POST
-f body='```suggestion const result = await fetchData(); return result.data;
  -f position[base_sha]="$base_sha" \
  -f position[head_sha]="$head_sha" \
  -f position[start_sha]="$start_sha" \
  -f position[position_type]="text" \
  -f position[new_path]="src/api.js" \
  -f position[new_line]=25

Workflow 5: Summarize Discussion Activity

工作流5：汇总讨论活动

bash
undefined
bash
undefined

Count discussions by state

按状态统计讨论数量

glab api projects/123/merge_requests/1/discussions --paginate |
jq '{ total: length, resolved: [.[] | select(.notes[0].resolved == true)] | length, unresolved: [.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false)] | length }'
undefined
glab api projects/123/merge_requests/1/discussions --paginate |
jq '{ total: length, resolved: [.[] | select(.notes[0].resolved == true)] | length, unresolved: [.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false)] | length }'
undefined

Troubleshooting

故障排查

IssueCauseSolution
400 Bad RequestMissing position fieldsInclude all required position fields
404 Discussion not foundInvalid discussion IDCheck discussion exists
Cannot resolveNot resolvable or not authorizedCheck note type and permissions
Position invalidWrong SHAs or line numbersGet fresh diff_refs from MR
Note emptyBody not setCheck 
-f body=...
parameter
问题原因解决方案
400 错误请求缺少位置字段包含所有必填的位置字段
404 讨论不存在无效的讨论ID确认讨论是否存在
无法标记为已解决讨论不可解决或无权限检查评论类型和权限
位置信息无效SHA或行号错误从合并请求获取最新的diff_refs
评论为空未设置内容检查
-f body=...
参数

Discussion vs Note

讨论与评论的区别

  • Discussion: A thread that can have multiple notes/replies
  • Note: A single comment within a discussion
  • Resolvable: Discussions on MR diffs can be resolved/unresolved
  • System notes: Auto-generated (commits, status changes) - not editable
  • 讨论: 可包含多条评论/回复的线程
  • 评论: 讨论中的单条留言
  • 可解决: 合并请求差异中的讨论可标记/取消标记为已解决
  • 系统评论: 自动生成的评论（如提交、状态变更），不可编辑

Related Documentation

相关文档