🤖 GitHub PR Review Agent

An AI-powered agent that automatically reviews GitHub Pull Requests and posts a detailed, human-like code review as a comment — complete with critical fixes, suggestions, and emojis. 🎉

Built on top of OpenAI Agents, Inngest (event-driven, durable step functions), Octokit (GitHub API), and Express.

---

📑 Table of Contents

• Overview
• Features
• Architecture
• How It Works
• Tech Stack
• Project Structure
• Getting Started
• Configuration
• Triggering a Review
• Agent Output Schema
• Security Notes

---

🔍 Overview

The GitHub PR Review Agent listens for a github/pullrequest.review event. When triggered, it:

1. Fetches the pull request metadata from GitHub.
2. Collects all the file changes (diffs / patches) in the PR.
3. Sends everything to an LLM-powered reviewer agent (gpt-4o).
4. Posts the structured review back to the PR as a comment.

The whole flow is orchestrated as durable steps using Inngest, so each stage is retried independently and survives failures.

---

✨ Features

• 🧠 AI Code Review — Uses OpenAI's gpt-4o model to analyze code changes.
• 🔁 Durable & Retryable — Each stage runs as an isolated Inngest step.
• 📦 Structured Output — Enforced via a zod schema (criticalFixes, suggestions, content, event).
• 🚦 Smart Skipping — Skips closed PRs or PRs with no changes.
• 💬 Auto-Commenting — Posts a formatted review comment directly on the PR.
• 😀 Natural Tone — Reviews include emojis to feel human-friendly.

---

🏗 Architecture

flowchart LR
    A[GitHub PR Event] -->|github/pullrequest.review| B[Inngest Function]
    B --> C[Express Server<br/>/api/inngest]
    C --> D{{Durable Steps}}
    D --> E[Octokit<br/>GitHub API]
    D --> F[OpenAI Agent<br/>gpt-4o]
    F -->|Structured Review| D
    D -->|Post Comment| E
    E --> G[(Pull Request<br/>Comment)]

Loading

---

⚙ How It Works

The core logic lives in inngest/functions/github-review.js and executes four durable steps:

sequenceDiagram
    participant EV as Event Trigger
    participant FN as Inngest Function
    participant GH as GitHub (Octokit)
    participant AI as OpenAI Agent

    EV->>FN: github/pullrequest.review<br/>{ owner, repo, pull_number }

    Note over FN,GH: Step 1 — Fetch PR Info
    FN->>GH: pulls.get()
    GH-->>FN: PR metadata

    alt PR not found or not open
        FN-->>EV: Skip review ⏭️
    end

    Note over FN,GH: Step 2 — Fetch Changes
    FN->>GH: pulls.listFiles() (paginated)
    GH-->>FN: file diffs / patches

    alt No changes
        FN-->>EV: Skip review ⏭️
    end

    Note over FN,AI: Step 3 — AI Analysis
    FN->>AI: run(agent, PR info + changes)
    AI-->>FN: { criticalFixes, suggestions, content, event }

    Note over FN,GH: Step 4 — Post Comment
    FN->>GH: issues.createComment()
    GH-->>FN: ✅ Comment posted

Loading

Step-by-step

Step	Name	Description
1️⃣	fetch-pull-request-information	Gets PR title, state, number, commits, head ref/sha, etc. Skips if not found or not open.
2️⃣	fetch-changes	Paginates through all changed files and extracts filename, status, patch, additions, deletions. Skips if empty.
3️⃣	ai-analysis	Runs the OpenAI agent with the PR info + changes and returns a structured review.
4️⃣	post-comment	Formats the review into sections and posts it as a GitHub PR comment.

---

🧰 Tech Stack

Layer	Technology
Runtime	Node.js (ES Modules)
Web Server	Express v5
Orchestration	Inngest — durable event-driven functions
AI Agent	@openai/agents (gpt-4o)
Schema Validation	Zod
GitHub API	@octokit/rest
Config	dotenv

---

📂 Project Structure

Github-PR-Review-Agent/
├── agents/
│   └── github-pr-review-agent.js   # OpenAI agent + zod output schema
├── inngest/
│   ├── client.js                   # Inngest client setup
│   └── functions/
│       ├── github-review.js        # Main 4-step review workflow
│       └── index.js                # Exported functions array
├── lib/
│   └── github.js                   # Octokit (GitHub API) client
├── index.js                        # Express server + Inngest serve handler
├── package.json
├── Pipeline.png                    # Architecture diagram
└── README.md

---

🚀 Getting Started

Prerequisites

• Node.js 18+ (ES Modules support)
• A GitHub Personal Access Token (PAT) with repo access
• An OpenAI API key
• Inngest Dev Server (for local development)

Installation

# 1. Clone the repository
git clone <your-repo-url>
cd Github-PR-Review-Agent

# 2. Install dependencies
npm install

# 3. Create your environment file (see Configuration below)
cp .env.example .env

# 4. Start the server
node index.js

The Express server starts on http://localhost:3000, exposing the Inngest endpoint at /api/inngest.

Running with Inngest Dev Server

In a separate terminal, start the Inngest dev server so it can discover and trigger your functions:

npx inngest-cli@latest dev

Then open the Inngest Dev UI (usually at http://localhost:8288) to inspect and manually trigger events.

---

🔐 Configuration

Create a .env file in the project root. Use the template below as .env.example:

# OpenAI API key used by the review agent
OPENAI_API_KEY="sk-..."

# GitHub Personal Access Token (repo scope)
GITHUB_PAT="github_pat_..."

# Enables Inngest dev mode
INNGEST_DEV="1"

Variable	Required	Description
OPENAI_API_KEY	✅	API key used by @openai/agents to call gpt-4o.
GITHUB_PAT	✅	GitHub token used by Octokit to read PRs and post comments.
INNGEST_DEV	⚙️	Set to 1 for local Inngest development.

---

📨 Triggering a Review

The workflow listens for the github/pullrequest.review event. Send an event with the following payload:

{
  "name": "github/pullrequest.review",
  "data": {
    "owner": "your-github-username",
    "repo": "your-repo-name",
    "pull_number": 42
  }
}

You can trigger it from the Inngest Dev UI, or programmatically:

import { inngest } from './inngest/client.js';

await inngest.send({
  name: 'github/pullrequest.review',
  data: { owner: 'octocat', repo: 'hello-world', pull_number: 42 },
});

💡 In production you'd typically wire a GitHub Webhook (on pull_request opened/synchronized) to forward these events to Inngest.

---

🧾 Agent Output Schema

The agent returns a validated object (via zod) defined in agents/github-pr-review-agent.js:

{
  criticalFixes?: string[] | null,  // Must-fix issues
  suggestions?:   string[] | null,  // Optional improvements
  content:        string,           // Main review body
  event:          'APPROVE' | 'COMMENT' | 'REQUEST_CHANGES'
}

The post-comment step formats this into Markdown sections:

<content>

**Critical Changes:**
- ...

**Suggestions:**
- ...

---

🛡 Security Notes

• Never commit your .env — it is already listed in .gitignore.
• Treat your OPENAI_API_KEY and GITHUB_PAT as secrets. If they are ever exposed, rotate them immediately.
• Scope your GitHub PAT to the minimum permissions required (read PRs + write comments).

---

📜 License

ISC © Contributors