pr-github-ops

PR GitHub 操作

Superagent PR 扫描在已通过身份验证的 gh CLI 沙箱中运行。交接后，GitHub 端的操作由你负责：行内发现项评论、受管理的标签以及检查运行的完成状态。

请先读取 pr-scan-context.json。其中包含 owner、repo、prNumber、headSha、checkRunId、reviewedFindingPaths 和 dismissedFingerprints。

关键规则：使用行内评论，而非讨论串评论

gh pr comment 会在 PR 对话讨论串中创建议题评论。这不适用于需要采取行动的发现项。

对于每个包含变更文件和差异行的发现项，请将其作为拉取请求审查评论发布，并锚定到“已更改的文件”视图中的对应行。

目标	错误方式	正确方式
在差异行上评论某个发现项	gh pr comment	gh api 审查评论，或带有 comments[] 的审查
不带行锚点的纯摘要说明	可以使用 gh pr comment	可选

如果你已经使用 gh pr comment 发布了发现项，请在扫描结束前删除这些议题评论，并重新发布为行内评论。

发布前检查

owner=OWNER
repo=REPO
pr=PR_NUMBER

# Existing inline review comments
gh api "repos/${owner}/${repo}/pulls/${pr}/comments" --paginate

# Existing general PR thread comments (avoid duplicating here)
gh api "repos/${owner}/${repo}/issues/${pr}/comments" --paginate

# PR diff files and patches (confirm path + line are in the diff)
gh api "repos/${owner}/${repo}/pulls/${pr}/files" --paginate

以下情况跳过发现项：

• file 位于 reviewedFindingPaths 中
• 行内评论中已存在该指纹
• 本次运行中你已在该 file 上发布过行内发现项（每个文件只发布一个行内发现项）

发现项评论正文格式

每条发现项评论都必须包含 Superagent 标记和指纹。

**P0:** Workflow uses pull_request_target trigger for untrusted fork PRs

Short evidence sentence here.

Short recommendation sentence here.

严重性与优先级的对应关系：critical → P0，high → P1，medium → P2，low → P3。

指纹：对规范化后的评论正文计算 SHA-256，然后再附加指纹行。转为小写、合并空白，并移除标记和任何已有的指纹评论。

body='
**P1:** Overly broad permissions: write-all in privileged workflow

Grants broad write access to GITHUB_TOKEN.

Replace with least-privilege job permissions.'

printf '%s' "$body" \
  | sed 's///g' \
  | tr '[:upper:]' '[:lower:]' \
  | tr -s '[:space:]' ' ' \
  | sed 's/^ //;s/ $//' \
  | sha256sum \
  | awk '{print $1}'

将指纹作为评论正文的最后一行附加。

在行内评论中使用 short_evidence 和 short_recommendation。内容应简短。

使用 gh api 发布行内审查评论

line 必须是 PR 差异中 path 的 RIGHT（新增）侧行号。发布前，请通过 PR 文件 API 或差异内容确认。

单条行内评论

head_sha=HEAD_SHA_FROM_CONTEXT

gh api \
  "repos/${owner}/${repo}/pulls/${pr}/comments" \
  -X POST \
  -f commit_id="$head_sha" \
  -f path=".github/workflows/example.yml" \
  -f side=RIGHT \
  -F line=12 \
  -f body="$comment_body"

数值字段使用 -F line=12。字符串使用 -f。

批量发布行内评论（有多个发现项时优先使用）

编写 review.json：

{
  "commit_id": "HEAD_SHA",
  "event": "COMMENT",
  "body": "\nSuperagent found 2 security concern(s).",
  "comments": [
    {
      "path": ".github/workflows/example.yml",
      "line": 4,
      "side": "RIGHT",
      "body": "\n**P0:** ...\n\n...\n\n"
    },
    {
      "path": ".github/workflows/example.yml",
      "line": 8,
      "side": "RIGHT",
      "body": "\n**P1:** ...\n\n...\n\n"
    }
  ]
}

发布：

gh api \
  "repos/${owner}/${repo}/pulls/${pr}/reviews" \
  -X POST \
  --input review.json

每次审查最多发布 50 条行内评论。如果发现项超过 50 条，请拆分为多次审查。

找不到差异行时的回退方式

只有当发现项在 PR 差异中没有有效的 file 和 line 时，才发布一条汇总议题评论：

gh api \
  "repos/${owner}/${repo}/issues/${pr}/comments" \
  -X POST \
  -f body="$fallback_body"

绝不要对同一个发现项同时发布行内评论和讨论串评论。

删除过期或位置错误的评论

# Delete inline review comment
gh api "repos/${owner}/${repo}/pulls/comments/COMMENT_ID" -X DELETE

# Delete general PR thread comment
gh api "repos/${owner}/${repo}/issues/comments/COMMENT_ID" -X DELETE

删除指纹不再属于当前发现项集合的过期 Superagent 发现项评论。删除已由行内评论替代的讨论串评论。

受管理的标签

只操作 Superagent 受管理的标签。保留所有无关标签。

gh pr edit "$pr" --repo "${owner}/${repo}" --add-label "pr:flagged"
gh pr edit "$pr" --repo "${owner}/${repo}" --remove-label "pr:verified"

扫描无发现项：

gh pr edit "$pr" --repo "${owner}/${repo}" --remove-label "pr:flagged" --add-label "pr:verified"

完成检查运行

使用上下文中的 checkRunId。始终设置 status=completed。

check_run_id=CHECK_RUN_ID_FROM_CONTEXT

gh api \
  "repos/${owner}/${repo}/check-runs/${check_run_id}" \
  -X PATCH \
  -f status=completed \
  -f conclusion=action_required \
  -f 'output[title]=PR requires security review' \
  -f 'output[summary]=2 security concern(s) detected.' \
  -f 'output[text]=Optional longer details.'

结论：

• success — 扫描无发现项
• action_required — 发现项需要审查
• neutral — 扫描结果不确定

端到端工作流

1. 读取 pr-scan-context.json 和 PR 输入 JSON。
2. 运行安全分析（其他技能），并生成包含 file、line、severity、title、short_evidence、short_recommendation 的发现项。
3. 列出已有的行内评论和讨论串评论；计算指纹；跳过已忽略、已审查或重复的发现项。
4. 使用 gh api 将发现项作为行内审查评论发布（单条评论或批量审查）。不要使用 gh pr comment 发布发现项。
5. 删除过期或位置错误的 Superagent 发现项评论。
6. 设置受管理的 PR 标签。
7. 完成检查运行。
8. 写入 Agent 回执 JSON，其中包含 github_operations_completed: true，并在可用时包含 posted_comment_ids。