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 の会話スレッドにイシューコメントを作成します。対応が必要な指摘には不適切です。

変更されたファイルと diff の行がある各指摘について、「変更されたファイル」ビューの該当行に紐付けて、プルリクエストのレビューコメントを投稿してください。

目的	誤り	正しい方法
diff の行にある指摘にコメントする	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 にインラインの指摘を投稿している（1 ファイルにつきインラインの指摘は 1 件）

指摘コメントの本文形式

すべての指摘コメントには、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 は、path に対する PR diff の右側（追加された側）の行番号でなければなりません。投稿前に PR files API または diff で確認してください。

インラインコメントを 1 件投稿する

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

1 件のレビューにつき、インラインコメントは最大 50 件まで投稿できます。指摘がそれ以上ある場合は、複数のレビューに分けてください。

diff の行が存在しない場合のフォールバック

PR diff 内に有効な file と line がない指摘に限り、まとめたイシューコメントを 1 件投稿してください。

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. github_operations_completed: true と、取得できる場合は posted_comment_ids を含むエージェントレシート JSON を書き込みます。