AI PR Reviewer

A reusable GitHub Action that provides automated code reviews using the Codex CLI tool. This action can be easily integrated into any repository to get AI-powered code reviews when a specific label is added to pull requests.

Quick Start

1. Create a Workflow in Your Repository

Create .github/workflows/ai-pr-review.yml in your repository:

name: AI PR Review

on:
  pull_request:
    types: [labeled]

jobs:
  ai-review:
    if: contains(github.event.label.name, 'AI Reviewer')
    uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@main
    secrets:
      GITHUB_TOKEN_REMOTE: ${{ secrets.GITHUB_TOKEN }}
      CLI_TOOL_API_TOKEN: ${{ secrets.CODEX_API_KEY }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

The CODEX_API_KEY secret is alreaady available as an organization secret, so no need to add it to individual repositories.

2. Add the Label

Create a label called "AI Reviewer" in your repository, or use the default label name.

3. Trigger a Review

Add the "AI Reviewer" label to any pull request to trigger an automated review!

Configuration Options

The action supports several input parameters for customization:

jobs:
  ai-review:
    uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@main
    with:
      trigger_label: "AI Reviewer" # Label that triggers review
      guidelines_path: ".github/pr-review-guidelines.md" # Deprecated; ignored for security
      package_version: "latest" # reviewer package version, not the Codex CLI version
      cli_version: "0.144.1" # Codex CLI pin for MCP compatibility
      post_as_review: true # Post as PR review vs comment
      max_files: 50 # Max files to review (0 = no limit)
    secrets:
      GITHUB_TOKEN_REMOTE: ${{ secrets.GITHUB_TOKEN }}
      CLI_TOOL_API_TOKEN: ${{ secrets.CODEX_API_KEY }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Input Parameters

| Parameter | Description | Default | Required | | --------------------- | --------------------------------------------------- | ----------------------------------- | -------- | | trigger_label | Label that triggers the AI review | 'AI Reviewer' | No | | guidelines_path | Deprecated; accepted but ignored | '' | No | | guidelines_paths | Deprecated; accepted but ignored | '' | No | | guidelines_template | Built-in guidelines template to use | 'default' | No | | package_version | Version of the reviewer package to use | 'latest' | No | | cli_version | Codex CLI version to install; @openai/codex@latest is forced to the MCP-compatible pin | '0.144.1' | No | | post_as_review | Post results as PR review (true) or comment (false) | true | No | | max_files | Maximum number of files to review (0 for no limit) | 50 | No | | min_severity | Minimum severity level for comments to be posted | 'medium' | No | | model | AI model to use for the review | | No | | enable_ai_labels | Enable AI Approved/Rejected labels on PRs | true | No |

Code Review Graph Integration (Codex)

When cli_command is set to codex, the reusable workflow automatically sets up code-review-graph:

• Installs Python 3.11 and code-review-graph from https://github.com/tirth8205/code-review-graph
• Registers a code-review-graph MCP server with Codex (code-review-graph serve)
• Builds the initial graph for the checked-out repository (code-review-graph build)

This makes graph-based impact analysis tools available during the PR review run.

The reviewer uses the checked-out repository, pr_review_context.md, pr_diff.patch, changed_files.txt, and the BASE_SHA/HEAD_SHA diff range as the primary source for changed code. GitHub MCP is configured when Codex is used, but it is supplemental metadata; the review prompt tells Codex to continue from local git context if MCP or network access is unavailable.

Required Secrets

| Secret | Description | Required | | --------------------- | ------------------------------------- | -------- | | GITHUB_TOKEN_REMOTE | GitHub token for API access | Yes | | CLI_TOOL_API_TOKEN | Codex API key for CLI authentication | Yes |

Custom Review Guidelines

guidelines_path and guidelines_paths are still accepted so existing caller workflows do not need to change, but they are ignored. Review instructions are loaded only from the centrally maintained prompt and guideline templates in this package.

Built-in Guidelines Templates

The AI PR Reviewer now includes specialized prompt templates for different types of reviews. You can use these templates by setting the guidelines_template parameter:

Available Templates

• default - General-purpose review guidelines covering code quality, security, and maintainability
• security-focused - Emphasizes security vulnerabilities, authentication, and data protection
• performance-focused - Focuses on performance optimization, scalability, and efficiency
• frontend-focused - Specialized for frontend development (React, Vue, Angular, accessibility)
• backend-focused - Specialized for backend development (APIs, databases, architecture)

Template Priority

The action uses guidelines in this priority order:

1. Built-in package template selected by guidelines_template
2. Built-in fallback guidelines

Comment Types and Severity Filtering

The AI will post different types of comments with severity levels:

• 🚨 Critical Issues: Security vulnerabilities, bugs, breaking changes (posted on specific lines)
• ⚠️ High Priority: Performance issues, major code quality concerns (posted on specific lines)
• 💡 Medium Priority: Code improvements, maintainability suggestions (posted on specific lines)
• 📝 Low Priority: Style suggestions, minor optimizations (posted on specific lines)
• 💬 General Comments: Architecture feedback, overall patterns (posted in summary review)

Filtering Comments by Severity

You can control which comments are posted by setting the min_severity parameter. Only comments at or above the specified severity level will be posted:

jobs:
  ai-review:
    uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@main
    with:
      min_severity: "high" # Only post critical and high severity comments
    secrets:
      GITHUB_TOKEN_REMOTE: ${{ secrets.GITHUB_TOKEN }}
      CLI_TOOL_API_TOKEN: ${{ secrets.CODEX_API_KEY }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Available severity levels (from highest to lowest):

• critical - Only critical issues
• high - Critical and high priority issues
• medium - Critical, high, and medium priority issues (default)
• low - All comments including low priority suggestions

AI Approval/Rejection Labels

The AI reviewer can automatically add labels to PRs based on its decision:

• ✅ AI Approved - The AI has reviewed the PR and found no significant issues
• ❌ AI Rejected - The AI has identified issues that should be addressed

This feature is enabled by default. To disable it, set enable_ai_labels: false:

jobs:
  ai-review:
    uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@main
    with:
      enable_ai_labels: false # Disable AI approval/rejection labels
    secrets:
      GITHUB_TOKEN_REMOTE: ${{ secrets.GITHUB_TOKEN }}
      CLI_TOOL_API_TOKEN: ${{ secrets.CODEX_API_KEY }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Note: The AI decision is based on the overall review and the severity of issues found. The labels are mutually exclusive - only one will be applied at a time.

Deploying Changes

This package is published to npm as @detiq/ai-pr-reviewer. Publishing is done manually after merging to main.

Deployment Steps

1. Make your changes in a feature branch
2. Update the version in package.json — this is the only file that needs a version bump:
   • 1.0.x — bug fixes, minor prompt tweaks
   • 1.x.0 — new features, non-breaking changes
   • x.0.0 — breaking changes
3. Run bun run type-check to catch any TypeScript errors
4. Open a PR, get it reviewed, and merge to main
5. Publish the package: npm publish

Testing Changes Before Merging

To test or debug changes before merging to main:

1. Set a pre-release version in package.json, e.g. "version": "1.0.5-beta.1"
2. Publish the package manually: npm publish --tag beta
3. In the consuming repo's workflow file, point to your branch and the beta version:

   uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@your-branch-name
   with:
     package_version: "1.0.5-beta.1"

4. Trigger a review on a PR in the consuming repo to debug your changes

Once done, revert the workflow reference back to @main before merging.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Examples

Basic Setup

The simplest way to get started:

# .github/workflows/ai-pr-review.yml
name: AI PR Review

on:
  pull_request:
    types: [labeled]

jobs:
  ai-review:
    if: contains(github.event.label.name, 'AI Reviewer')
    uses: detiq/ai-pr-reviewer-workflows/.github/workflows/pr-reviewer.yml@main
    secrets:
      GITHUB_TOKEN_REMOTE: ${{ secrets.GITHUB_TOKEN }}
      CLI_TOOL_API_TOKEN: ${{ secrets.CODEX_API_KEY}}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

How It Works

1. Label Detection: When a PR is labeled with the trigger label, the workflow activates
2. Repository Checkout: The action checks out your repository
3. Package Installation: Installs the @detiq/ai-pr-reviewer NPM package containing prompt templates
4. Guidelines Resolution: Loads centrally maintained package templates, then falls back to defaults
5. LLM CLI Setup: Installs and configures the selected models' CLI tool
6. PR Analysis: Analyzes the PR changes using the specified guidelines
7. Results Posting: Posts the review as either a PR review or comment

NPM Package

The prompt templates are distributed as an NPM package: @detiq/ai-pr-reviewer

Package Versioning

The package is automatically published when:

• Changes are made to the prompts/ directory
• A new release is created
• Manual workflow dispatch is triggered

This ensures that all consuming repositories get the latest prompt improvements automatically.

Testing Different Package Versions

You can test different versions of the package using the package_version parameter:

# Test with latest published version (default)
with:
  package_version: "latest"

# Test with specific stable version
with:
  package_version: "1.0.2"

# Test with beta/pre-release version
with:
  package_version: "beta"