github-pr-review

name	github-pr-review
description	Use when reviewing GitHub pull requests with gh CLI - creates pending reviews with code suggestions, batches comments, and chooses appropriate event types (COMMENT/APPROVE/REQUEST_CHANGES)

GitHub PR Review

Overview

Workflow for reviewing GitHub pull requests using gh api to create pending reviews with code suggestions. Always use pending reviews to batch comments, even under time pressure.

When to Use

• Reviewing pull requests
• Adding code suggestions to PRs
• Posting review comments with the gh CLI

Core Workflow

REQUIRED STEPS (do not skip):

1. Draft the review - Analyze PR and prepare all comments
2. Post the review

Technical Workflow

# Step 1: Create PENDING review (no event field)
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews \
  -X POST \
  -f commit_id="<COMMIT_SHA>" \
  -f 'comments[][path]=path/to/file.ts' \
  -F 'comments[][line]=<LINE_NUMBER>' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Comment text

```suggestion
// suggested code here

Additional explanation...'
--jq '{id, state}'

Returns: {"id": <REVIEW_ID>, "state": "PENDING"}

Step 2: Submit the pending review

gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>/events
-X POST
-f event="COMMENT"
-f body="Optional overall review message"

## Event Types

Choose the appropriate event type when submitting:

| Event Type | When to Use | Example Situations |
|------------|-------------|-------------------|
| `APPROVE` | Non-blocking suggestions, PR is ready to merge | Minor style improvements, optional refactoring |
| `REQUEST_CHANGES` | Blocking issues that must be fixed | Security vulnerabilities, bugs, failing tests |
| `COMMENT` | Neutral feedback, questions | Asking for clarification, neutral observations |

## Quick Reference

### Getting Prerequisites

```bash
# Get commit SHA
gh pr view <PR_NUMBER> --json commits --jq '.commits[-1].oid'

# Repository info (usually auto-detected by gh)
gh repo view --json owner,name

Required Parameters

• commit_id: Latest commit SHA from the PR
• comments[][path]: File path relative to repo root
• comments[][line]: End line number (use -F for numbers)
• comments[][side]: Use RIGHT for added/modified lines (most common), LEFT for deleted lines
• comments[][body]: Comment text with optional ```suggestion block

Optional Parameters

• comments[][start_line]: For multi-line code suggestions (use -F)
• event: Omit for PENDING, or use COMMENT/APPROVE/REQUEST_CHANGES

Syntax Rules

✅ DO:

• Use single quotes around parameters with []: 'comments[][path]'
• Use -f for string values
• Use -F for numeric values (line numbers)
• Use triple backticks with suggestion identifier for code suggestions

❌ DON'T:

• Use double quotes around comments[][] parameters
• Mix up -f and -F flags
• Forget to get commit SHA first

Code Suggestions Format

-f 'comments[][body]=Your comment explaining the issue

```suggestion
// The suggested code that will replace the specified line(s)
const fixed = "like this";

Additional context or explanation after the suggestion.'

**Important**: Code suggestions replace the entire line or line range. Make sure the suggested code is complete and correct.

### Edge Case: Suggestions with Nested Code Blocks

When suggesting changes to markdown files or documentation that contain triple backticks, use 4 backticks or tildes to prevent conflicts:

`````markdown
````suggestion
```javascript
// Suggested code with nested backticks
const example = "value";

Or use tildes:

````suggestion
```javascript
const example = "value";
````

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Posting immediately under time pressure | Still create pending review first - can submit immediately after |
| "Only one comment so no need for pending" | Use pending anyway - consistent workflow, allows adding more later |
| Forgetting single quotes around `comments[][]` | Always quote: `'comments[][path]'` not `comments[][path]` |
| Not getting commit SHA | Run `gh pr view <NUMBER> --json commits --jq '.commits[-1].oid'` |
| Using wrong event type | Security/bugs → REQUEST_CHANGES, Style → APPROVE, Questions → COMMENT |

## Red Flags - You're About to Violate the Pattern

Stop if you're thinking:
- "User said ASAP so I'll skip pending review"
- "Only one comment so I'll post directly"
- "Time pressure means I should post immediately"
- "I'll post this one now and batch the rest later"

**Why pending reviews?** Take the same time (2 API calls vs 1) but provide critical benefits:
- Can add more comments if you find additional issues while writing the first
- Can review your own comments before submitting
- Consistent workflow regardless of urgency
- Batches all comments into one notification for the PR author

**Example**

```bash
# Create pending review with multiple comments
gh api repos/:owner/:repo/pulls/123/reviews \
  -X POST \
  -f commit_id="abc123" \
  -f 'comments[][path]=src/auth.ts' \
  -F 'comments[][line]=20' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=First issue...' \
  -f 'comments[][path]=src/auth.ts' \
  -F 'comments[][line]=35' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Second issue...' \
  -f 'comments[][path]=tests/auth.test.ts' \
  -F 'comments[][line]=12' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Third issue...' \
  --jq '{id, state}'

# Submit with appropriate event type
gh api repos/:owner/:repo/pulls/123/reviews/<REVIEW_ID>/events \
  -X POST \
  -f event="REQUEST_CHANGES" \
  -f body="Found 3 issues that need to be addressed before merging."

Real-World Impact

Without this pattern:

• Multiple separate notifications spam the PR author
• Can't batch feedback together
• Easy to forget issues while reviewing
• Inconsistent workflow based on perceived urgency

With this pattern:

• All feedback in one coherent review
• PR author gets one notification with full context
• Can refine comments before posting
• Professional, organized reviews