# Github Code Review

> Reviews local git diffs and open GitHub PRs: checklists, inline comments, approve or request-changes via gh or REST. Use when reviewing code before push, reviewing PR #N, or posting a formal GitHub review. Not for opening or merging PRs (github-pr-workflow) and not a local-only git chair (git-workflow).

- Skill: `kayforkind/github-code-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kayforkind/github-code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kayforkind/github-code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: Kayforkind (https://skillmd.com/u/kayforkind)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/kayforkind/github-code-review

---


# GitHub Code Review

Perform code reviews on local changes before pushing, or review open pull requests on GitHub. Most of this skill uses plain `git`; the `gh`/`curl` split only matters for PR-level interactions (viewing PR metadata, posting comments, submitting formal reviews).

## When to Use

- User asks to "review the code", "check before pushing", or "review my changes" → use the **Pre-Push Review Workflow** (Section 1 / Section 4).
- User says "review PR #N", "look at this PR", or provides a GitHub PR URL → use the **PR Review Workflow** (Section 5).
- User wants to leave inline comments, approve, or request changes on a PR → use the **PR Review Workflow**.
- User wants a quick diff scan for secrets, debug statements, or conflict markers → use the **Pre-Push Review Workflow**.

## Prerequisites

- Authenticated with GitHub (see `github-auth` skill).
- Inside a git repository.
- For PR interactions: either `gh` CLI installed and authenticated, **or** a `GITHUB_TOKEN` environment variable available.

### Setup (for PR interactions)

Run this setup block before any PR-level commands. It detects whether `gh` is available and authenticated; if not, it falls back to `git` + REST API using `GITHUB_TOKEN`.

**Windows (PowerShell) note:** The bash snippets below work in Git Bash or WSL. In native PowerShell, use the PowerShell equivalents noted where relevant. All `git` commands work identically in PowerShell.

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
    fi
  fi
fi

REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
```

**PowerShell equivalent for owner/repo extraction:**

```powershell
$remoteUrl = git remote get-url origin
$ownerRepo = ($remoteUrl -replace '.*github\.com[:/]','' -replace '\.git$','')
$OWNER, $REPO = $ownerRepo -split '/'
```

> **HARD RULE:** Never print or log `GITHUB_TOKEN`. Never commit it to any file. Use `YOUR_KEY` placeholders in examples.

## Procedure

---

### 1. Reviewing Local Changes (Pre-Push)

This is pure `git` — works everywhere, no API needed.

#### Get the Diff

```bash
# Staged changes (what would be committed)
git diff --staged

# All changes vs main (what a PR would contain)
git diff main...HEAD

# File names only
git diff main...HEAD --name-only

# Stat summary (insertions/deletions per file)
git diff main...HEAD --stat
```

#### Review Strategy

1. **Get the big picture first:**

```bash
git diff main...HEAD --stat
git log main..HEAD --oneline
```

2. **Review file by file** — use `read_file` on changed files for full context, and the diff to see what changed:

```bash
git diff main...HEAD -- src/auth/login.py
```

3. **Check for common issues:**

```bash
# Debug statements, TODOs, console.logs left behind
git diff main...HEAD | grep -n "print(\|console\.log\|TODO\|FIXME\|HACK\|XXX\|debugger"

# Large files accidentally staged
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10

# Secrets or credential patterns
git diff main...HEAD | grep -in "password\|secret\|api_key\|token.*=\|private_key"

# Merge conflict markers
git diff main...HEAD | grep -n "<<<<<<\|>>>>>>\|======="
```

4. **Present structured feedback** to the user using the output format below.

#### Review Output Format

When reviewing local changes, present findings in this structure:

```
## Code Review Summary

### Critical
- **src/auth.py:45** — SQL injection: user input passed directly to query.
  Suggestion: Use parameterized queries.

### Warnings
- **src/models/user.py:23** — Password stored in plaintext. Use bcrypt or argon2.
- **src/api/routes.py:112** — No rate limiting on login endpoint.

### Suggestions
- **src/utils/helpers.py:8** — Duplicates logic in `src/core/utils.py:34`. Consolidate.
- **tests/test_auth.py** — Missing edge case: expired token test.

### Looks Good
- Clean separation of concerns in the middleware layer
- Good test coverage for the happy path
```

> **Reference:** Load `references/review-output-template.md` when you need the canonical summary-comment template for posting to GitHub. Use it in Step 8 of the PR workflow.

---

### 2. Reviewing a Pull Request on GitHub

#### View PR Details

**With gh:**

```bash
gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only
```

**With git + curl:**

```bash
PR_NUMBER=123

# Get PR details
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "
import sys, json
pr = json.load(sys.stdin)
print(f\"Title: {pr['title']}\")
print(f\"Author: {pr['user']['login']}\")
print(f\"Branch: {pr['head']['ref']} -> {pr['base']['ref']}\")
print(f\"State: {pr['state']}\")
print(f\"Body:\n{pr['body']}\")"

# List changed files
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/files \
  | python3 -c "
import sys, json
for f in json.load(sys.stdin):
    print(f\"{f['status']:10} +{f['additions']:-4} -{f['deletions']:-4}  {f['filename']}\")"
```

#### Check Out PR Locally for Full Review

This works with plain `git` — no `gh` needed:

```bash
# Fetch the PR branch and check it out
git fetch origin pull/123/head:pr-123
git checkout pr-123

# Now you can use read_file, search_files, run tests, etc.

# View diff against the base branch
git diff main...pr-123
```

**With gh (shortcut):**

```bash
gh pr checkout 123
```

#### Leave Comments on a PR

**General PR comment — with gh:**

```bash
gh pr comment 123 --body "Overall looks good, a few suggestions below."
```

**General PR comment — with curl:**

```bash
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
  -d '{"body": "Overall looks good, a few suggestions below."}'
```

#### Leave Inline Review Comments

**Single inline comment — with gh (via API):**

```bash
HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')

gh api repos/$OWNER/$REPO/pulls/123/comments \
  --method POST \
  -f body="This could be simplified with a list comprehension." \
  -f path="src/auth/login.py" \
  -f commit_id="$HEAD_SHA" \
  -f line=45 \
  -f side="RIGHT"
```

**Single inline comment — with curl:**

```bash
# Get the head commit SHA
HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments \
  -d "{
    \"body\": \"This could be simplified with a list comprehension.\",
    \"path\": \"src/auth/login.py\",
    \"commit_id\": \"$HEAD_SHA\",
    \"line\": 45,
    \"side\": \"RIGHT\"
  }"
```

#### Submit a Formal Review (Approve / Request Changes)

**With gh:**

```bash
gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "See inline comments."
gh pr review 123 --comment --body "Some suggestions, nothing blocking."
```

**With curl — multi-comment review submitted atomically:**

```bash
HEAD_SHA=$(curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"COMMENT\",
    \"body\": \"Code review from Hermes Agent\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"Use parameterized queries to prevent SQL injection.\"},
      {\"path\": \"src/models/user.py\", \"line\": 23, \"body\": \"Hash passwords with bcrypt before storing.\"},
      {\"path\": \"tests/test_auth.py\", \"line\": 1, \"body\": \"Add test for expired token edge case.\"}
    ]
  }"
```

Event values: `"APPROVE"`, `"REQUEST_CHANGES"`, `"COMMENT"`.

> **HARD RULE:** The `line` field refers to the line number in the *new* version of the file. For deleted lines, use `"side": "LEFT"`. Posting an inline comment on a line that is not part of the diff will fail with a 422 error.

---

### 3. Review Checklist

When performing a code review (local or PR), systematically check each category:

#### Correctness
- Does the code do what it claims?
- Edge cases handled (empty inputs, nulls, large data, concurrent access)?
- Error paths handled gracefully?

#### Security
- No hardcoded secrets, credentials, or API keys
- Input validation on user-facing inputs
- No SQL injection, XSS, or path traversal
- Auth/authz checks where needed

#### Code Quality
- Clear naming (variables, functions, classes)
- No unnecessary complexity or premature abstraction
- DRY — no duplicated logic that should be extracted
- Functions are focused (single responsibility)

#### Testing
- New code paths tested?
- Happy path and error cases covered?
- Tests readable and maintainable?

#### Performance
- No N+1 queries or unnecessary loops
- Appropriate caching where beneficial
- No blocking operations in async code paths

#### Documentation
- Public APIs documented
- Non-obvious logic has comments explaining "why"
- README updated if behavior changed

---

### 4. Pre-Push Review Workflow

When the user asks you to "review the code" or "check before pushing":

1. `git diff main...HEAD --stat` — see scope of changes
2. `git diff main...HEAD` — read the full diff
3. For each changed file, use `read_file` if you need more context
4. Apply the checklist (Section 3)
5. Present findings in the structured format (Critical / Warnings / Suggestions / Looks Good)
6. If critical issues found, offer to fix them before the user pushes

---

### 5. PR Review Workflow (End-to-End)

When the user asks you to "review PR #N", "look at this PR", or gives you a PR URL, follow this recipe:

#### Step 1: Set up environment

Use the setup block in **Prerequisites** (detect `gh` vs `GITHUB_TOKEN`, extract `OWNER`/`REPO`). If the `github-auth` skill is installed, follow that skill's env helper instead of duplicating token extraction.

#### Step 2: Gather PR context

Get the PR metadata, description, and list of changed files to understand scope before diving into code.

**With gh:**
```bash
gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123
```

**With curl:**
```bash
PR_NUMBER=123

# PR details (title, author, description, branch)
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER

# Changed files with line counts
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/files
```

#### Step 3: Check out the PR locally

This gives you full access to `read_file`, `search_files`, and the ability to run tests.

```bash
git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER
```

#### Step 4: Read the diff and understand changes

```bash
# Full diff against the base branch
git diff main...HEAD

# Or file-by-file for large PRs
git diff main...HEAD --name-only
# Then for each file:
git diff main...HEAD -- path/to/file.py
```

For each changed file, use `read_file` to see full context around the changes — diffs alone can miss issues visible only with surrounding code.

#### Step 5: Run automated checks locally (if applicable)

```bash
# Run tests if there's a test suite
python -m pytest 2>&1 | tail -20
# or: npm test, cargo test, go test ./..., etc.

# Run linter if configured
ruff check . 2>&1 | head -30
# or: eslint, clippy, etc.
```

#### Step 6: Apply the review checklist (Section 3)

Go through each category: Correctness, Security, Code Quality, Testing, Performance, Documentation.

#### Step 7: Post the review to GitHub

Collect your findings and submit them as a formal review with inline comments.

**With gh:**
```bash
# If no issues — approve
gh pr review $PR_NUMBER --approve --body "Reviewed by Hermes Agent. Code looks clean — good test coverage, no security concerns."

# If issues found — request changes with inline comments
gh pr review $PR_NUMBER --request-changes --body "Found a few issues — see inline comments."
```

**With curl — atomic review with multiple inline comments:**
```bash
HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# Build the review JSON — event is APPROVE, REQUEST_CHANGES, or COMMENT
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/reviews \
  -d "{
    \"commit_id\": \"$HEAD_SHA\",
    \"event\": \"REQUEST_CHANGES\",
    \"body\": \"## Hermes Agent Review\n\nFound 2 issues, 1 suggestion. See inline comments.\",
    \"comments\": [
      {\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"🔴 **Critical:** User input passed directly to SQL query — use parameterized queries.\"},
      {\"path\": \"src/models.py\", \"line\": 23, \"body\": \"⚠️ **Warning:** Password stored without hashing.\"},
      {\"path\": \"src/utils.py\", \"line\": 8, \"body\": \"💡 **Suggestion:** This duplicates logic in core/utils.py:34.\"}
    ]
  }"
```

#### Step 8: Also post a summary comment

In addition to inline comments, leave a top-level summary so the PR author gets the full picture at a glance. Use the review output format from `references/review-output-template.md`.

**With gh:**
```bash
gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
## Code Review Summary

**Verdict: Changes Requested** (2 issues, 1 suggestion)

### 🔴 Critical
- **src/auth.py:45** — SQL injection vulnerability

### ⚠️ Warnings
- **src/models.py:23** — Plaintext password storage

### 💡 Suggestions
- **src/utils.py:8** — Duplicated logic, consider consolidating

### ✅ Looks Good
- Clean API design
- Good error handling in the middleware layer

---
*Reviewed by Hermes Agent*
EOF
)"
```

#### Step 9: Clean up

```bash
git checkout main
git branch -D pr-$PR_NUMBER
```

#### Decision: Approve vs Request Changes vs Comment

- **Approve** — no critical or warning-level issues, only minor suggestions or all clear
- **Request Changes** — any critical or warning-level issue that should be fixed before merge
- **Comment** — observations and suggestions, but nothing blocking (use when you're unsure or the PR is a draft)

## Pitfalls

- **Inline comment line numbers must be in the diff.** Posting an inline comment on a line that was not changed in the PR will return HTTP 422. The `line` field must reference a line present in the diff hunk. For deleted lines, use `"side": "LEFT"` and the original line number.
- **`HEAD_SHA` must match the current PR head.** If the author pushes a new commit between your checkout and your review submission, the `commit_id` will be stale and the API will reject it. Re-fetch `HEAD_SHA` immediately before posting.
- **`gh pr checkout` creates a detached or local branch.** Always clean up with `git checkout main && git branch -D pr-NNN` to avoid stale branches accumulating.
- **Token leakage.** Never echo `$GITHUB_TOKEN` in debug output. Never paste it into a commit message, PR body, or inline comment. Use `YOUR_KEY` in any shared examples.
- **`git diff main...HEAD` vs `git diff main..HEAD`.** The triple-dot syntax (`...`) compares the merge-base of `main` and `HEAD` — this is what you want for a PR-style diff. The double-dot (`..`) compares the tips directly and will include unrelated changes on `main`.
- **Large diffs may be truncated by `gh pr diff`.** For very large PRs, check out locally and use `git diff` instead, or paginate the REST API `files` endpoint.
- **PowerShell quoting.** The bash heredoc (`<<'EOF'`) syntax does not work in native PowerShell. Use a here-string (`@'...'@`) or write the body to a temp file and pass `--body-file`.
- **Draft PRs.** You cannot `--approve` a draft PR. Use `--comment` instead until the author marks it ready for review.
- **Rate limits.** Unauthenticated or lightly scoped tokens may hit GitHub API rate limits during large reviews. Check `gh api rate_limit` or the `X-RateLimit-Remaining` header if requests start failing.

## Verification

After completing a review, verify your work:

```bash
# Verify the review was posted (gh)
gh pr view $PR_NUMBER --json reviews --jq '.reviews[-1] | {state: .state, body: .body[:80]}'

# Verify inline comments were posted (gh)
gh api repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments --jq '.[-3:] | .[] | {path: .path, line: .line, body: .body[:60]}'

# Verify summary comment was posted (gh)
gh pr view $PR_NUMBER --json comments --jq '.comments[-1].body[:80]'

# Verify local cleanup
git branch --list 'pr-*'
# Should show nothing after cleanup
```

**With curl:**
```bash
# Check the latest review
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r[-1]['state'], r[-1]['body'][:80])"

# Check rate limit remaining
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit \
  | python3 -c "import sys,json; print('Remaining:', json.load(sys.stdin)['resources']['core']['remaining'])"
```

**Expected output for a successful review submission:**
```
REQUEST_CHANGES ## Hermes Agent Review
Found 2 issues, 1 suggestion. See inline comments.
```

## Related skills

- **github-auth** — Authentication setup, token extraction, `gh-env.sh` script
- **github-pr-workflow** — Broader PR lifecycle: create, update, merge, close