GitHub PR Review Bot Template

A GitHub app template built with Mastra AI that provides intelligent, multi-agent code review for pull requests. This bot automatically analyzes PRs using customizable AI agents. The included example agents focus on security and code style, but the intention is that you write your own custom agents for your codebase and policies.

Features

  • Multi-Agent Review System: Uses customizable AI agents for different aspects of code review
  • Intelligent Summarization: Provides concise, actionable feedback
  • Automatic Approval: Can automatically approve PRs that meet all criteria
  • Context-Aware: Discovers and analyzes relevant files for comprehensive reviews

Architecture

This template uses:

  • Mastra: AI agent framework for workflows and multi-agent coordination
  • Probot: GitHub App framework for handling webhooks
  • TypeScript: Full type safety and modern JavaScript features
  • OpenAI: AI models for intelligent code analysis (Other models can also be used. See Mastra docs for model providers

Prerequisites

  • Node.js >= 22
  • A GitHub App with appropriate permissions
  • OpenAI API key

Quick Start

1. Clone and Install

 1git clone https://github.com/zengenuity/mastra-pr-reviewer
 2cd mastra-pr-reviewer
 3npm install

2. Create a GitHub App

  1. Run npm build.
  2. Run npm start
  3. Go to http://localhost:3000.
  4. Click on the Register a GitHub App link.
  5. Add a name for your bot and create your bot.
  6. Install your bot in one or more repositories.
  7. Ctrl-C to quit the bot.

Note: GitHub app needs the following permissions:

  • Contents: Read Only
  • Metadata: Read Only
  • Pull Requests: Read and Write

These permissions should be automatically set for you as the default when you install via the above method.

3. Environment Setup

If you have followed the steps above, your .env file will already contain all the GitHub-related values. You just need to add your AI model keys, such as:

OPENAI_API_KEY=sk-your-openai-api-key

Otherwise, for manual setup:

  1. Copy .env.example to .env:

    cp .env.example .env

  2. Fill in your environment variables:

     1# From your GitHub App settings
 2GITHUB_APP_ID=123456
 3GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
 4your_actual_private_key_content
 5-----END RSA PRIVATE KEY-----"
 6GITHUB_WEBHOOK_SECRET=your_webhook_secret
 7
 8# From OpenAI
 9OPENAI_API_KEY=sk-your-openai-api-key

4. Local Development

If you followed the automated steps above, you will already have a smee.io webhook proxy URL defined and set in your .env file. Otherwise:

For local testing, use smee.io to proxy webhooks:

  1. Visit https://smee.io and get a unique URL
  2. Add it to your .env: 
    WEBHOOK_PROXY_URL=https://smee.io/your-unique-url
  3. Update your GitHub App's webhook URL to use the smee URL

5. Build and Run

 1# Build the TypeScript
 2npm run build
 3
 4# Start the bot
 5npm start

Customization

Modifying Agents

The bot uses specialized agents in src/mastra/agents/:

Review Agents:

  • SecurityAgent src/mastra/agents/security-agent.ts: Focuses on security vulnerabilities
  • CodeStyleAgent src/mastra/agents/code-style-agent.ts: Enforces coding standards

Post-Processing Agent:

  • SummarizationAgent src/mastra/agents/summarization-agent.ts: Takes review results and creates concise, actionable summaries

Each agent can be customized by modifying their domain-specific instructions the agent file listed above. The system instructions that are passed to all agents can be modified in src/mastra/utils/agent-instructions.ts.

Adding New Agents

  1. Create a new agent file in src/mastra/agents/
  2. Extend the BasePRAgent class
  3. Add it to the workflow in src/mastra/workflows/pr-review-workflow.ts

Workflow Customization

The main workflow is in src/mastra/workflows/pr-review-workflow.ts. You can:

  • Add new steps
  • Modify the approval logic
  • Change the review criteria
  • Add additional integrations

Memory and Context

The bot maintains context using Mastra's memory system with structured schemas. Modify src/mastra/schemas/agent-schemas.ts to change the data structure.

Support