name	gh-pr-review
description	Review GitHub pull requests using gh CLI. Approve, request changes, or comment on PRs. Use when user wants to provide PR feedback or approval.
allowed-tools	Bash, Read, Grep, Glob
handoffs	[object Object], [object Object]

GitHub PR Review Skill

Review pull requests using the gh CLI with comprehensive feedback options.

When to Use

User asks to "review the PR" or "approve PR #123"
User wants to request changes on a PR
User wants to leave comments on a PR
Before merging, to provide approval
User wants to review code changes in a PR

Prerequisites

Verify GitHub CLI is installed and authenticated:

gh --version
gh auth status

Execution Workflow

Step 1: View PR for Review

First, examine the PR to review:

# View PR overview
gh pr view 123

# View diff
gh pr diff 123

# View specific files
gh pr diff 123 --patch | grep -A 50 "src/auth.ts"

# Check CI status
gh pr checks 123

Step 2: Analyze Changes

Review the code:

Check diff stats:

gh pr diff 123 --stat

Review commits:

gh pr view 123 --json commits \
  | jq -r '.commits[] | "\(.messageHeadline)"'

Check tests:

gh pr diff 123 | grep -A 10 "\.test\."

Look for issues:
- Code quality problems
- Security vulnerabilities
- Missing tests
- Breaking changes
- Style violations

Step 3: Provide Review

Choose review type based on findings:

APPROVE - Code is good to merge

gh pr review 123 --approve

REQUEST CHANGES - Issues must be fixed

gh pr review 123 --request-changes \
  --body "Please address the following issues before merging."

COMMENT - Feedback without approval/rejection

gh pr review 123 --comment \
  --body "Looks good overall, minor suggestions below."

Step 4: Add Review Comments

General comment on PR:

gh pr review 123 --approve --body "$(cat <<'EOF'
Great work! Code looks good overall.

Highlights:
- Clean implementation
- Good test coverage
- Follows team conventions

Suggestions:
- Consider extracting auth logic to separate module
- Add JSDoc for public API

Ready to merge! ✓
EOF
)"

Comment on specific file/line:

gh pr comment 123 \
  --body "Consider using const instead of let here" \
  --body-file review-comments.md

Request changes with specific issues:

gh pr review 123 --request-changes --body "$(cat <<'EOF'
Please address these issues:

## Security
- ⚠️ SQL injection vulnerability in user.ts:45
- ⚠️ Missing input validation in auth.ts:89

## Code Quality
- Consider extracting duplicate logic in handlers
- Missing error handling in payment.ts:123

## Tests
- Add test for edge case: empty user input
- Integration test needed for auth flow

Please update and re-request review.
EOF
)"

Step 5: Follow Up

After review submitted:

# Verify review was posted
gh pr view 123 --json reviews \
  | jq -r '.reviews[-1] | "\(.author.login): \(.state)"'

# Check if PR can now be merged
gh pr view 123 --json reviewDecision
# APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED

# Monitor for updates
gh pr view 123 --comments

Common Scenarios

Scenario 1: Quick Approval

# Simple approval for straightforward PRs
gh pr view 123  # Quick review
gh pr checks 123  # Verify CI passed
gh pr review 123 --approve --body "LGTM! ✓"

Scenario 2: Thorough Code Review

# Comprehensive review process

# 1. Get PR context
gh pr view 123 --json title,body,commits

# 2. Review all changes
gh pr diff 123 --patch > /tmp/pr-123.diff
# Review the diff file carefully

# 3. Check for common issues
gh pr diff 123 | grep -E "(TODO|FIXME|XXX|HACK)"
gh pr diff 123 | grep -E "(console\.log|debugger|print)"
gh pr diff 123 | grep -i "password.*=.*['\"]"

# 4. Verify tests exist
TEST_FILES=$(gh pr diff 123 --name-only | grep -c "\.test\.")
SRC_FILES=$(gh pr diff 123 --name-only | grep -c "\.ts$")
echo "Test coverage: $TEST_FILES tests for $SRC_FILES source files"

# 5. Check CI
gh pr checks 123

# 6. Provide detailed review
gh pr review 123 --approve --body "$(cat <<'EOF'
Excellent work! Comprehensive review completed.

✓ Code Quality: Clean, readable, follows conventions
✓ Security: No vulnerabilities found
✓ Tests: Good coverage (5 new tests)
✓ Performance: No concerns
✓ Documentation: Well documented

Ready to merge!
EOF
)"

Scenario 3: Request Changes with Specific Feedback

# Found issues that need addressing

gh pr review 123 --request-changes --body "$(cat <<'EOF'
Good progress, but please address these issues:

## Critical Issues
1. **Security**: SQL injection in `src/db/user.ts:45`
   ```typescript
   // Current (vulnerable):
   db.query(`SELECT * FROM users WHERE id = ${userId}`)

   // Should be:
   db.query('SELECT * FROM users WHERE id = ?', [userId])

Bug: Race condition in src/auth/session.ts:89
- Missing mutex/lock when updating session
- Could lead to concurrent modification issues

Non-Critical Improvements

Consider extracting validation logic to separate file
Add JSDoc comments for public API methods
Update README with new auth flow

Testing

Missing test for expired token scenario
Integration test needed for full auth flow

Please address critical issues and re-request review. EOF )"


### Scenario 4: Provide Comments Without Blocking

```bash
# Suggestions but not blocking merge

gh pr review 123 --comment --body "$(cat <<'EOF'
Nice work! A few optional suggestions:

**Performance Optimization:**
- Could cache the API response in `api.ts:123`
- Consider lazy loading the auth module

**Code Organization:**
- Might be cleaner to split `handlers.ts` into separate files
- Consider extracting constants to `config.ts`

These are just suggestions - feel free to merge as-is or address later!
EOF
)"

Scenario 5: Review Multiple PRs in Batch

# Review all PRs from a specific author

gh pr list --author alice --json number,title \
  | jq -r '.[] | .number' \
  | while read pr; do
    echo "Reviewing PR #$pr..."

    # Quick check
    gh pr diff $pr --stat
    gh pr checks $pr

    # Auto-approve if small and tests pass
    CHANGES=$(gh pr diff $pr --stat | tail -1 | grep -oE '[0-9]+ insertions' | grep -oE '[0-9]+')
    CI_STATUS=$(gh pr checks $pr --json state --jq '.[].state' | sort -u)

    if [[ $CHANGES -lt 50 ]] && [[ "$CI_STATUS" == "SUCCESS" ]]; then
      gh pr review $pr --approve --body "Auto-approved: Small change, CI passed ✓"
      echo "✓ PR #$pr approved"
    else
      echo "⏭ PR #$pr requires manual review"
    fi
  done

Scenario 6: Re-review After Changes

# Re-review after author addressed feedback

# Check what changed since last review
gh pr view 123 --json reviews,commits \
  | jq -r '
    .reviews[-1].submittedAt as $last_review |
    .commits[] |
    select(.committedDate > $last_review) |
    .messageHeadline
  '

# View new changes
gh pr diff 123

# Approve if issues addressed
gh pr review 123 --approve --body "$(cat <<'EOF'
Thanks for addressing the feedback!

✓ Security issues resolved
✓ Tests added
✓ Documentation updated

Approving now!
EOF
)"

Advanced Review Techniques

Automated Security Checks

# Security review automation

# Check for secrets/credentials
gh pr diff 123 | grep -iE "(api[_-]?key|password|secret|token|credential)"

# Check for debugging code
gh pr diff 123 | grep -E "(console\.log|debugger|print\()"

# Check for TODOs/FIXMEs
gh pr diff 123 | grep -E "(TODO|FIXME|XXX|HACK)"

# Check for unsafe patterns
gh pr diff 123 | grep -E "(eval\(|innerHTML|dangerouslySetInnerHTML)"

# Report findings
if [ $? -eq 0 ]; then
  gh pr review 123 --request-changes --body "Security concerns found - see comments"
fi

Automated Code Quality Checks

# Run linters on PR changes
gh pr diff 123 --name-only | grep "\.ts$" | while read file; do
  npx eslint "$file" || echo "Lint errors in $file"
done

# Check test coverage
gh pr diff 123 --name-only | grep "\.test\." || \
  echo "⚠️ No test files in PR"

# Verify documentation
gh pr diff 123 --name-only | grep -q "README\|docs/" || \
  echo "⚠️ Consider updating documentation"

Compare with Base Branch

# Check complexity increase
BASE_BRANCH=$(gh pr view 123 --json baseRefName --jq '.baseRefName')

# Lines of code delta
ADDITIONS=$(gh pr view 123 --json additions --jq '.additions')
DELETIONS=$(gh pr view 123 --json deletions --jq '.deletions')
NET_CHANGE=$((ADDITIONS - DELETIONS))

echo "Net change: +$NET_CHANGE lines"

if [ $NET_CHANGE -gt 500 ]; then
  echo "⚠️ Large PR - consider breaking into smaller pieces"
fi

Review Checklist Automation

# Automated review checklist

PR_NUM=123
CHECKLIST=""

# 1. Check tests added
if gh pr diff $PR_NUM --name-only | grep -q "\.test\."; then
  CHECKLIST+="✓ Tests added\n"
else
  CHECKLIST+="⚠️ No tests found\n"
fi

# 2. Check CI status
if gh pr checks $PR_NUM | grep -q "✓"; then
  CHECKLIST+="✓ CI passed\n"
else
  CHECKLIST+="❌ CI failing\n"
fi

# 3. Check size
CHANGES=$(gh pr view $PR_NUM --json additions,deletions --jq '.additions + .deletions')
if [ $CHANGES -lt 300 ]; then
  CHECKLIST+="✓ Reasonable size ($CHANGES lines)\n"
else
  CHECKLIST+="⚠️ Large PR ($CHANGES lines)\n"
fi

# 4. Check documentation
if gh pr diff $PR_NUM --name-only | grep -qE "(README|docs/)"; then
  CHECKLIST+="✓ Documentation updated\n"
else
  CHECKLIST+="ℹ️ No documentation changes\n"
fi

# Post checklist as review
gh pr review $PR_NUM --comment --body "$(echo -e "Review Checklist:\n\n$CHECKLIST")"

Tips

Review promptly: Don't let PRs sit for days
Be constructive: Suggest improvements, don't just criticize
Test locally: For complex PRs, check out and test locally
Check tests: Always verify tests are included and passing
Security first: Look for security vulnerabilities
Ask questions: Use comments to clarify unclear code
Approve explicitly: Don't assume - explicitly approve when ready
Use templates: Create review templates for consistency

Error Handling

Error: "Not authorized to review"

Cause: Insufficient permissions or reviewing your own PR
Solution: Verify repository access or ask another reviewer

Error: "Pull request is not open"

Cause: PR is closed or merged
Solution: Verify PR status with gh pr view 123

Error: "Review already submitted"

Cause: You already reviewed this version
Solution: Wait for new commits or edit existing review

Error: "Cannot approve your own PR"

Cause: GitHub prevents self-approval
Solution: Request review from teammates

Best Practices

Review completely: Check code, tests, docs, CI
Be specific: Point to exact lines/files with issues
Suggest solutions: Don't just point out problems
Approve explicitly: When ready, explicitly approve
Request changes clearly: List all issues that must be fixed
Use comments for suggestions: Don't block merge for minor issues
Test complex changes: Check out PR locally for thorough testing
Check security: Always look for security vulnerabilities
Verify tests: Ensure adequate test coverage
Be timely: Review within 24 hours when possible

Review Guidelines

When to APPROVE

Code is high quality
Tests are comprehensive
No security issues
Follows team conventions
CI passes
Documentation adequate

When to REQUEST CHANGES

Security vulnerabilities
Critical bugs
Missing tests for new features
Breaking changes without migration
Violates team standards
CI failing

When to COMMENT

Minor suggestions
Style preferences
Performance optimizations
Future improvements
Questions about approach
Positive feedback

Related Skills

gh-pr-view - View PR details before reviewing
gh-pr-merge - Merge approved PRs
gh-pr-create - Create new PRs
gh-pr-ready - Mark draft as ready

Limitations

Cannot review your own PRs
Limited to text-based review (no visual diff in CLI)
Cannot suggest specific code changes (use web UI for suggestions)
No threading support for conversations
Cannot resolve conversations via CLI

gh-pr-review

Install Skill

SKILL.md