PR Code Reviewer

A GitHub Action that automatically reviews pull requests using Google's Gemini AI. Comment /code-review on any PR and get inline feedback posted directly to the diff.

---

How it works

The reviewer uses two strategies depending on PR size, automatically chosen at runtime:

Strategy	When	How
Single-pass	files < 5 AND lines < 50	One LLM call with the full diff — fast and cheap
Agentic	files >= 5 OR lines >= 50	Iterative loop: Gemini calls tools (get_file, search_code, post_inline_comment, etc.) up to a configurable iteration/timeout budget, then posts a summary

If the agentic loop times out or hits max iterations, it falls back to single-pass automatically. Comments already posted mid-loop are kept.

---

Quickstart

You do not need to clone this repo. Add a workflow file to your own repository:

# .github/workflows/code-review.yml
name: AI Code Review

on:
  issue_comment:
    types: [created]

jobs:
  review:
    if: github.event.issue.pull_request != null
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: emna-khemiri/PR-Code-Reviewer@main
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Then comment /code-review on any open PR. That's it.

Secrets to add

Go to your repo → Settings → Secrets and variables → Actions → New repository secret:

Secret	Where to get it
GEMINI_API_KEY	Google AI Studio
GITHUB_TOKEN	Automatically provided by GitHub — no setup needed

---

All inputs

- uses: emna-khemiri/PR-Code-Reviewer@main
  with:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

    # Model — swap tiers without changing anything else
    MODEL: 'gemini-2.5-flash'         # default

    # Routing thresholds (both must be under threshold to use single-pass)
    SMALL_PR_FILES_THRESHOLD: '5'     # default
    SMALL_PR_LINES_THRESHOLD: '50'    # default

    # Agentic loop limits
    MAX_ITERATIONS: '6'               # max tool-call rounds
    TIMEOUT_MS: '30000'              # wall-clock budget (ms)

    # Quality filter
    MIN_CONFIDENCE_TO_POST: 'high'   # low | medium | high

    # Rate limiting (5 = free-tier Gemini, 60+ = paid)
    GEMINI_RPM: '5'

    # Exclude files from review (comma-separated globs)
    EXCLUDE: '*.lock,*.min.js'

    # Append team coding conventions to the cached system prompt
    CODING_CONVENTIONS: ''

    # Optional: LangSmith tracing
    ENABLE_LANGSMITH: 'false'
    LANGSMITH_PROJECT: 'gemini-ai-code-reviewer'

---

Trigger commands

Comment one of these on any open PR:

Command	Description
/code-review	Trigger a review (recommended)
/gemini-review	Legacy alias, same behaviour

---

Testing the two strategies

Testing single-pass

Open a small PR with fewer than 5 files and fewer than 50 changed lines, then comment /code-review. The workflow log will show:

Strategy: SINGLE_PASS

Testing the agentic loop

Option A — make a real large PR (≥5 files or ≥50 changed lines).

Option B — force agentic on any PR by setting the thresholds to zero in your workflow:

- uses: emna-khemiri/PR-Code-Reviewer@main
  with:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
    SMALL_PR_FILES_THRESHOLD: '0'   # forces agentic on every PR
    SMALL_PR_LINES_THRESHOLD: '0'

The workflow log will show:

Strategy: AGENTIC
Tool call: get_file(...)
Tool call: search_code(...)
...

If the loop exhausts its budget you will see:

Strategy: FALLBACK_SINGLE_PASS

---

Architecture

review_code_gemini.py          ← entry point (called by the Action)
gemini_reviewer/
  config.py                    ← all env-var config
  code_reviewer.py             ← orchestrator
  router.py                    ← picks strategy, posts summary + check
  single_pass.py               ← single LLM call path
  agent_loop.py                ← iterative tool-calling loop
  agent_tools.py               ← 5 tools: get_file, search_code,
                                           get_pr_details, get_test_file,
                                           post_inline_comment
  gemini_client.py             ← Gemini API (retry, caching, fn-calling)
  github_client.py             ← GitHub API (diff, comments, Checks)
  diff_parser.py               ← unified diff → structured model
  models.py                    ← data classes and enums

---

Common configurations

Tighter review (post medium-confidence findings too)

MIN_CONFIDENCE_TO_POST: 'medium'

Larger agentic budget

MAX_ITERATIONS: '12'
TIMEOUT_MS: '60000'

Skip generated files

EXCLUDE: '*.lock,*.min.js,*_pb2.py,dist/**'

Add team conventions

CODING_CONVENTIONS: |
  - All API handlers must validate input with Pydantic.
  - No bare except clauses — always catch specific exceptions.
  - Every public function needs a docstring.

---

Requirements

• A Google Gemini API key (free tier works — set GEMINI_RPM: '5')
• A GitHub repo with Actions enabled
• PR write permissions (the default GITHUB_TOKEN is enough)

---

License

MIT