pr-github-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR GitHub operations

PR GitHub 操作

Superagent PR scans run in a sandbox with an authenticated

gh

CLI. You own GitHub side effects after handoff: inline finding comments, managed labels, and check-run completion.

Read

pr-scan-context.json

first. It contains

owner

repo

prNumber

headSha

checkRunId

reviewedFindingPaths

, and

dismissedFingerprints

Superagent PR 扫描在 sandbox 中运行，并使用已完成身份验证的

gh

CLI。交接后，由你负责 GitHub 侧操作：发布内联发现评论、管理 Superagent 管理的标签，以及完成 check run。

首先读取

pr-scan-context.json

。其中包含

owner

、

repo

、

prNumber

、

headSha

、

checkRunId

、

reviewedFindingPaths

和

dismissedFingerprints

。

Critical rule: inline comments, not thread comments

关键规则：使用内联评论，不要使用会话线程评论

gh pr comment

creates issue comments on the PR conversation thread. That is wrong for actionable findings.

For each finding with a changed file and diff line, post a pull request review comment anchored to that line in the Files changed view.

Goal	Wrong	Right
Comment on a finding at a diff line	`gh pr comment`	`gh api` review comment or review with `comments[]`
Summary-only note with no line anchor	`gh pr comment` is acceptable	optional

If you already posted findings with

gh pr comment

, delete those issue comments and repost inline before finishing the scan.

gh pr comment

会在 PR 会话线程中创建 issue comments。对于可操作的发现，这种方式是错误的。

对于每个具有变更文件和 diff 行的发现，在 Files changed 视图中发布一条锚定到该行的 pull request review comment。

目标	错误方式	正确方式
评论 diff 行上的发现	`gh pr comment`	使用 `gh api` 创建 review comment，或使用包含 `comments[]` 的 review
仅包含摘要且没有行锚点的说明	`gh pr comment` 可以接受	可选

如果你已经使用

gh pr comment

发布了发现，请删除这些 issue comments，并在完成扫描前重新以内联方式发布。

Inspect before posting

发布前检查

bash

owner=OWNER
repo=REPO
pr=PR_NUMBER

bash

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


Skip findings when:
- `file` is in `reviewedFindingPaths`
- fingerprint already exists in an inline comment
- you already posted an inline finding on that `file` this run (one inline finding per file)

gh api "repos/${owner}/${repo}/pulls/${pr}/files" --paginate


出现以下情况时跳过发现：
- `file` 已包含在 `reviewedFindingPaths` 中
- 某条内联评论中已经存在相同的 fingerprint
- 本次运行期间已经针对该 `file` 发布过内联发现（每个 `file` 仅发布一条内联发现）

Finding comment body format

发现评论正文格式

Every finding comment must include the Superagent marker and fingerprint.

markdown

<!-- brin-pr-finding -->
**P0:** Workflow uses pull_request_target trigger for untrusted fork PRs

Short evidence sentence here.

Short recommendation sentence here.

<!-- superagent-finding-fingerprint:HEX_SHA256 -->

Severity to priority:

critical

→ P0,

high

→ P1,

medium

→ P2,

low

→ P3.

Fingerprint: SHA-256 of the normalized comment body before appending the fingerprint line. Lowercase, collapse whitespace, remove the marker and any existing fingerprint comment.

bash

body='<!-- brin-pr-finding -->
**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/<!-- brin-pr-finding -->//g' \
  | tr '[:upper:]' '[:lower:]' \
  | tr -s '[:space:]' ' ' \
  | sed 's/^ //;s/ $//' \
  | sha256sum \
  | awk '{print $1}'

Append the fingerprint as the last line of the comment body.

Use

short_evidence

and

short_recommendation

in inline comments. Keep them terse.

每条发现评论都必须包含 Superagent marker 和 fingerprint。

markdown

<!-- brin-pr-finding -->
**P0:** Workflow uses pull_request_target trigger for untrusted fork PRs

Short evidence sentence here.

Short recommendation sentence here.

<!-- superagent-finding-fingerprint:HEX_SHA256 -->

严重级别与优先级对应关系：

critical

→ P0，

high

→ P1，

medium

→ P2，

low

→ P3。

Fingerprint：在追加 fingerprint 行之前，对评论正文进行规范化并计算 SHA-256。转换为小写、折叠空白字符，并移除 marker 和任何已有的 fingerprint 注释。

bash

body='<!-- brin-pr-finding -->
**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/<!-- brin-pr-finding -->//g' \
  | tr '[:upper:]' '[:lower:]' \
  | tr -s '[:space:]' ' ' \
  | sed 's/^ //;s/ $//' \
  | sha256sum \
  | awk '{print $1}'

将 fingerprint 作为评论正文的最后一行追加。

在内联评论中使用

short_evidence

和

short_recommendation

，并保持简洁。

Post inline review comments with gh api

使用 gh api 发布内联 review comment

line

must be a line number on the RIGHT (added) side of the PR diff for

path

. Confirm with the PR files API or diff before posting.

line

必须是 PR diff 中

path

的 RIGHT（新增）侧行号。发布前通过 PR files API 或 diff 进行确认。

Single inline comment

单条内联评论

bash

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"

Use

-F line=12

for numeric fields. Use

-f

for strings.

bash

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

。

Batch inline comments (preferred for multiple findings)

批量内联评论（存在多条发现时推荐使用）

Write

review.json

json

{
  "commit_id": "HEAD_SHA",
  "event": "COMMENT",
  "body": "<!-- brin-pr-finding -->\nSuperagent found 2 security concern(s).",
  "comments": [
    {
      "path": ".github/workflows/example.yml",
      "line": 4,
      "side": "RIGHT",
      "body": "<!-- brin-pr-finding -->\n**P0:** ...\n\n...\n\n<!-- superagent-finding-fingerprint:abc123... -->"
    },
    {
      "path": ".github/workflows/example.yml",
      "line": 8,
      "side": "RIGHT",
      "body": "<!-- brin-pr-finding -->\n**P1:** ...\n\n...\n\n<!-- superagent-finding-fingerprint:def456... -->"
    }
  ]
}

Post it:

bash

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

Post at most 50 inline comments per review. If you have more findings, split across multiple reviews.

编写

review.json

：

json

{
  "commit_id": "HEAD_SHA",
  "event": "COMMENT",
  "body": "<!-- brin-pr-finding -->\nSuperagent found 2 security concern(s).",
  "comments": [
    {
      "path": ".github/workflows/example.yml",
      "line": 4,
      "side": "RIGHT",
      "body": "<!-- brin-pr-finding -->\n**P0:** ...\n\n...\n\n<!-- superagent-finding-fingerprint:abc123... -->"
    },
    {
      "path": ".github/workflows/example.yml",
      "line": 8,
      "side": "RIGHT",
      "body": "<!-- brin-pr-finding -->\n**P1:** ...\n\n...\n\n<!-- superagent-finding-fingerprint:def456... -->"
    }
  ]
}

发布 review：

bash

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

每个 review 最多发布 50 条内联评论。如果发现数量超过 50 条，请拆分到多个 review 中发布。

Fallback when no diff line exists

没有 diff 行时的回退方案

Only when a finding has no valid

file

line

in the PR diff, post a single consolidated issue comment:

bash

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

Never post the same finding both inline and on the thread.

仅当某个发现在 PR diff 中没有有效的

file

line

时，才发布一条合并后的 issue comment：

bash

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

绝不要将同一个发现同时发布为内联评论和会话线程评论。

Delete stale or misplaced comments

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

bash

undefined

bash

undefined

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


Delete stale Superagent finding comments whose fingerprints are no longer in the current findings set. Delete thread comments you replaced with inline comments.

gh api "repos/${owner}/${repo}/issues/comments/COMMENT_ID" -X DELETE


删除 fingerprint 已不在当前发现集合中的过期 Superagent 发现评论。删除已被内联评论替换的会话线程评论。

Managed labels

管理标签

Only touch Superagent managed labels. Preserve all unrelated labels.

bash

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

Clean scan:

bash

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

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

bash

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

扫描无问题时：

bash

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

Complete the check run

完成 check run

Use

checkRunId

from context. Always set

status=completed

bash

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

Conclusions:

```
success
```
— clean scan
```
action_required
```
— findings need review
```
neutral
```
— inconclusive scan

使用上下文中的

checkRunId

。始终设置

status=completed

。

bash

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
```
— 扫描结果不确定

End-to-end workflow

端到端工作流

Read
```
pr-scan-context.json
```
and PR input JSON.
Run security analysis (other skills) and produce findings with
```
file
```
,
```
line
```
,
```
severity
```
,
```
title
```
,
```
short_evidence
```
,
```
short_recommendation
```
.
List existing inline and thread comments; compute fingerprints; skip dismissed/reviewed/duplicate findings.
Post findings as inline review comments with
```
gh api
```
(single comment or batch review). Do not use
```
gh pr comment
```
for findings.
Delete stale or misplaced Superagent finding comments.
Set managed PR labels.
Complete the check run.

Write the agent receipt JSON with

github_operations_completed: true

and

posted_comment_ids

when available.

读取
```
pr-scan-context.json
```
和 PR 输入 JSON。
运行安全分析（使用其他 skill），并生成包含
```
file
```
、
```
line
```
、
```
severity
```
、
```
title
```
、
```
short_evidence
```
和
```
short_recommendation
```
的发现结果。
列出已有的内联评论和会话线程评论；计算 fingerprint；跳过已忽略、已审查或重复的发现。
使用
```
gh api
```
将发现发布为内联 review comment（单条评论或批量 review）。不要使用
```
gh pr comment
```
发布发现。
删除过期或放错位置的 Superagent 发现评论。
设置 Superagent 管理的 PR 标签。
完成 check run。
写入 Agent receipt JSON，并在可用时包含
```
github_operations_completed: true
```
和
```
posted_comment_ids
```
。