---
name: pr-github-ops
description: Post Superagent PR security scan findings as inline GitHub pull request review comments using the authenticated gh CLI. Use whenever you need to comment on a PR scan finding, manage Superagent PR labels, complete a GitHub check run, or avoid posting findings as general PR thread comments. Trigger for any Superagent sandbox PR scan handoff that owns GitHub side effects via gh.
---
# PR GitHub operations
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`.
## 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.
## Inspect before posting
```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)
## 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.
## Post inline review comments with gh api
`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.
### 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.
### 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.
### Fallback when no diff line exists
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.
## Delete stale or misplaced comments
```bash
# 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.
## 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"
```
## Complete the 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
## End-to-end workflow
1. Read `pr-scan-context.json` and PR input JSON.
2. Run security analysis (other skills) and produce findings with `file`, `line`, `severity`, `title`, `short_evidence`, `short_recommendation`.
3. List existing inline and thread comments; compute fingerprints; skip dismissed/reviewed/duplicate findings.
4. Post findings as inline review comments with `gh api` (single comment or batch review). Do not use `gh pr comment` for findings.
5. Delete stale or misplaced Superagent finding comments.
6. Set managed PR labels.
7. Complete the check run.
8. Write the agent receipt JSON with `github_operations_completed: true` and `posted_comment_ids` when available.