Code Review GitHub Integration

Orchestrates GitHub PR workflows for AI code review. Provides tools to list pull requests, post inline review comments, apply labels based on review findings, and (with explicit opt-in) auto-merge clean PRs.

All GitHub API interactions go through the gh CLI. Direct HTTP requests and web searches are denied to ensure all operations are auditable and respect GitHub's rate limiting.

Authentication

bash
export GH_TOKEN="ghp_..."

The token needs read-write access since this skill posts comments, applies labels, and can merge PRs:

| Scope (classic PAT) | Fine-grained permission | Why | |----------------------|------------------------|-----| | repo | Pull requests: Read & Write | List PRs, post review comments, merge | | repo | Contents: Read | Read PR diff and file contents | | repo | Issues: Write | Apply and remove labels | | read:org (optional) | Organization: Read | Org-level label policies |

Minimum fine-grained token permissions: pull_requests: write, contents: read, issues: write on the target repository.

For read-only review without GitHub interaction, use the code-review skill instead — it only needs read access.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GH_TOKEN | yes | GitHub personal access token or fine-grained token | | REVIEW_AUTO_MERGE | no | Set to true to enable guarded auto-merge. Default: disabled | | REVIEW_LABEL_PREFIX | no | Prefix for review labels (default: review/). Labels: review/approved, review/needs-changes, review/security-concern |

Tool: review_github_list_prs

List open pull requests for a repository, optionally filtered by author or label.

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repo | string | yes | Repository in owner/repo format | | author | string | no | Filter by PR author username | | label | string | no | Filter by label | | limit | integer | no | Maximum PRs to return (default: 10, max: 100) |

Output: JSON array of pull requests with number, title, author, url, labels, created_at, updated_at, mergeable_state.

Detection Heuristics

The agent selects this tool when it detects:

• Requests to "list PRs", "show open pull requests", "what PRs need review"
• Requests to find PRs by a specific author or with specific labels

Tool: review_github_post_comments

Post inline review comments on a GitHub pull request based on code review findings.

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repo | string | yes | Repository in owner/repo format | | pr_number | integer | yes | Pull request number | | findings | array | yes | Array of findings from code_review_diff output | | submit_review | boolean | no | Submit as a formal review (not just individual comments). Default: true | | review_event | string | no | Review event type: COMMENT, APPROVE, REQUEST_CHANGES. Default: COMMENT |

Each finding in the array should have: file, line, severity, title, description, suggestion.

Output: JSON object with comments_posted, review_url, and any errors for comments that failed.

Detection Heuristics

The agent selects this tool when it detects:

• Requests to "post review comments", "comment on the PR", "submit review"
• After running code_review_diff, user asks to post findings to GitHub

Comment Format

Comments are posted as inline review comments with this format:

**[severity] category: title**

description

💡 **Suggestion:** suggestion

Tool: review_github_apply_labels

Apply review-status labels to a pull request based on review findings.

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repo | string | yes | Repository in owner/repo format | | pr_number | integer | yes | Pull request number | | risk_level | string | yes | Overall risk level from review: low, medium, high, critical | | has_security_findings | boolean | no | Whether security issues were found. Default: false |

Output: JSON object with labels_applied and labels_removed.

Label Mapping

| Risk Level | Label Applied | |------------|---------------| | low | review/approved | | medium | review/needs-changes | | high | review/needs-changes | | critical | review/security-concern |

If has_security_findings is true, review/security-concern is always applied regardless of risk level.

Previous review labels (with the configured prefix) are removed before applying new ones.

Detection Heuristics

The agent selects this tool when it detects:

• Requests to "label the PR", "apply review labels", "mark PR as approved"
• After completing a review, user asks to update PR status

Tool: review_github_auto_merge

Merge a pull request after verifying safety conditions. Requires explicit opt-in via REVIEW_AUTO_MERGE=true.

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repo | string | yes | Repository in owner/repo format | | pr_number | integer | yes | Pull request number | | merge_method | string | no | Merge method: merge, squash, rebase. Default: squash | | require_clean_review | boolean | no | Require no error-severity findings before merging. Default: true | | review_result | object | no | Review result from code_review_diff to verify cleanliness |

Output: JSON object with merged, sha, message, or blocked_reason if merge was prevented.

Detection Heuristics

The agent selects this tool when it detects:

• Requests to "merge the PR", "auto-merge if clean"
• Requests to "merge after review passes"

Safety Guards

This tool enforces multiple safety layers:

1. Env var gate: REVIEW_AUTO_MERGE must be explicitly set to true. If unset or any other value, merge is blocked with a clear message.
2. Clean review required: By default, the PR must have no error-severity findings. Override with require_clean_review: false.
3. CI checks: All required status checks must pass (enforced by GitHub's branch protection).
4. No dismissed reviews: The tool never dismisses existing review requests or approvals.
5. Merge conflicts: GitHub API rejects merges with conflicts — the tool surfaces this clearly.

Workflow: Full PR Review Cycle

A typical end-to-end review workflow using all three code-review skills:

1. List PRs → review_github_list_prs to find PRs needing review
2. Run review → code_review_diff with the PR URL to generate findings
3. Post comments → review_github_post_comments to post findings as inline comments
4. Apply labels → review_github_apply_labels to set status labels
5. Auto-merge (optional) → review_github_auto_merge if review is clean and opt-in is enabled

Safety Constraints

This skill MUST:

• Never merge without REVIEW_AUTO_MERGE=true explicitly set
• Never dismiss existing reviews or review requests
• Never force-push or modify PR branch contents
• Never delete branches (leave that to GitHub's auto-delete setting)
• Never bypass branch protection rules
• Never approve its own PRs (if the token belongs to the PR author)
• Post comments as the authenticated user — never impersonate
• All GitHub operations go through gh CLI — http_request and web_search tools are denied
• Rate-limit awareness: back off on 403/429 responses from GitHub API

Autonomous Compatibility

This skill is designed to work in automated pipelines:

• All inputs and outputs are structured JSON
• Error states return JSON with error field and descriptive messages
• Idempotent: re-running label application or comment posting produces consistent results
• Labels are prefix-scoped to avoid conflicting with other label systems