gitlab-discussion

讨论技能

通过 glab api 原始端点调用管理 GitLab 线程讨论。

快速参考

操作	命令模式	风险
列出 MR 讨论	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	⚠️⚠️

风险说明：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

• 用户提到“讨论”“线程”或“对话”
• 用户想要添加代码审查评论
• 用户提到“解决”或“取消解决”讨论
• 用户想要回复现有评论或线程
• 用户想要在 MR 中添加针对特定行的评论

以下情况绝不要使用：

• 用户想要添加简单备注或评论（使用 glab mr note 或 glab issue note）
• 用户想要审查 MR 变更（使用 gitlab-mr）
• 用户想要搜索评论（使用带 notes 范围的 gitlab-search）

API 前提条件

必需的令牌范围： api

权限：

• 读取讨论：Reporter+（适用于私有仓库）
• 创建讨论：Reporter+
• 解决讨论：Developer+（或 MR 作者）

可用命令

列出 MR 讨论

# List all discussions on MR
glab api projects/123/merge_requests/1/discussions --method GET

# With pagination
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"

列出议题讨论

# List all discussions on issue
glab api projects/123/issues/42/discussions --method GET

# With pagination
glab api projects/123/issues/42/discussions --paginate

获取特定讨论

# Get MR discussion by ID
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

在 MR 上创建讨论

# Create general discussion
glab api projects/123/merge_requests/1/discussions --method POST \
  -f body="This looks good overall, but I have some suggestions."

# 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

# 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

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

在议题上创建讨论

# Create discussion
glab api projects/123/issues/42/discussions --method POST \
  -f body="I think we should reconsider this approach."

回复讨论

# Reply to MR discussion
glab api projects/123/merge_requests/1/discussions/abc123/notes --method POST \
  -f body="Good point, I'll fix this."

# Reply to issue discussion
glab api projects/123/issues/42/discussions/def456/notes --method POST \
  -f body="I agree with the above."

解决/取消解决讨论

# Resolve MR discussion
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

更新评论

# Update note in discussion
glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method PUT \
  -f body="Updated comment text"

删除评论

# Delete note from discussion
glab api projects/123/merge_requests/1/discussions/abc123/notes/789 --method DELETE

Diff 评论的位置对象

要在 MR 中添加针对特定行的评论，需要提供位置信息：

字段	必需	描述
base_sha	是	基础提交的 SHA（目标分支）
head_sha	是	头部提交的 SHA（源分支）
start_sha	是	起始提交的 SHA
position_type	是	代码使用 text，图像使用 image
new_path	新增/修改时需要	新版本中的路径
new_line	新增/修改时需要	新版本中的行号
old_path	删除时需要	旧版本中的路径
old_line	删除时需要	旧版本中的行号

获取位置所需的 SHA

# Get MR details to find SHAs
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"

常见工作流

工作流 1：审查 MR 并添加评论

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')

# Add comment on line 42 of new file
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

工作流 2：解决所有讨论

# 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

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

# 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])"'

工作流 4：添加建议

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

工作流 5：汇总讨论活动

# 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
  }'

故障排除

问题	原因	解决方案
400 Bad Request	缺少位置字段	包含所有必需的位置字段
404 Discussion not found	讨论 ID 无效	检查讨论是否存在
无法解决	不可解决或未获授权	检查评论类型和权限
位置无效	SHA 或行号错误	从 MR 获取最新的 diff_refs
评论为空	未设置正文	检查 -f body=... 参数

讨论与评论

• 讨论：可包含多条评论或回复的线程
• 评论：讨论中的单条评论
• 可解决：MR 差异中的讨论可以解决或取消解决
• 系统备注：自动生成（提交、状态变更）——不可编辑

相关文档

• API 辅助工具
• 安全措施
• 快速参考
• GitLab 讨论 API