Pull Reviews - AI Powered Video Review

Automated video reviews for GitHub pull requests. Pull Reviews analyzes your PR diffs with AI, generates narrated walkthrough scripts, renders short videos with syntax-highlighted code, and posts them back as PR comments.

How it works

PR event → Fetch diff → AI analysis → Narration script → TTS → Syntax highlighting → Video render → Upload → PR comment

1. A PR is opened or updated (via GitHub Actions or webhook)
2. Pull Reviews fetches the diff and resolves configuration (presets, auto-detection, per-PR overrides)
3. An LLM (OpenAI, Anthropic, or Claude on Vertex AI) analyzes the diff for purpose, risks, and significance
4. A narration script is generated with time-budgeted scenes
5. TTS generates MP3 audio for each scene (OpenAI or Kokoro local)
6. Shiki syntax-highlights the diff hunks with green/red line coloring
7. Remotion renders a 1920x1080 H.264 video at 30fps
8. The video uploads to S3-compatible storage (Cloudflare R2, AWS S3, etc.)
9. A comment with the video and review summary is posted (or updated) on the PR

Video scenes

Scene	Description
Title Card	PR title, author, repo, branch badges, +/- stats
File Overview	Animated file tree with language icons and change bars
Diff Walkthrough	Per-file syntax-highlighted code with narration
Risk Callout	Severity-colored risk items (critical/warning/info)
Summary	Sentiment badge, review summary, quick stats

All scenes are individually toggleable via configuration.

Quick start

GitHub Actions (recommended)

Copy this workflow to .github/workflows/pull-reviews.yml in any repo:

name: Video Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write
  id-token: write

jobs:
  review:
    uses: ambient-code/pull-reviews/.github/workflows/review.yml@main
    with:
      s3_bucket: pull-reviews
    secrets:
      S3_ENDPOINT: ${{ secrets.S3_ENDPOINT }}
      S3_ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY_ID }}
      S3_SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_ACCESS_KEY }}
      CDN_BASE_URL: ${{ secrets.CDN_BASE_URL }}

No API keys needed for analysis when using Vertex AI with Workload Identity Federation. TTS falls back to Kokoro (free, local) when no OpenAI key is provided.

CLI usage (test against a real PR)

cp .env.example .env
# Fill in GITHUB_TOKEN

# Build the Docker image
npm run docker:build

# Review a PR
docker compose run --rm review owner/repo 42
docker compose run --rm review owner/repo 42 --preset=security

Webhook server

# Fill in all GitHub App credentials in .env
npm run docker:build
npm run docker:server

The server listens on port 3001 and processes pull_request events (opened/synchronize).

Local development (Remotion Studio)

npm install
npm run dev

Opens Remotion Studio for previewing compositions with default props. Requires Chromium on the host.

Configuration

Pull Reviews is deeply configurable through multiple layers:

1. Environment variables — base settings
2. .pull-reviews.yml in your repo — per-repo defaults
3. Built-in presets — quick, thorough, security, architecture, onboarding
4. Auto-detection — from branch names, commit prefixes, file patterns, labels
5. PR body overrides — <!-- pull-reviews ... --> YAML blocks

See docs/configuration.md for the full reference.

Documentation

Document	Description
Configuration	Full config reference — presets, YAML, env vars, auto-detection
Architecture	System design, pipeline flow, data model
Deployment	Docker setup, GitHub App, S3 storage, production checklist
Scenes & Video	Video composition structure, scene details, styling
CLI Reference	Local testing commands and options
LLM Analysis	How AI review works — prompts, providers, output format

Environment variables

See .env.example for the full list. Key variables:

Variable	Required	Description
GITHUB_TOKEN	CLI only	Personal access token for CLI testing
GITHUB_APP_ID	Server	GitHub App ID
GITHUB_PRIVATE_KEY	Server	GitHub App private key (PEM or base64)
GITHUB_WEBHOOK_SECRET	Server	Webhook signature verification
LLM_PROVIDER	No	openai, anthropic, or vertex
TTS_PROVIDER	No	openai or local (Kokoro, default when no OpenAI key)
S3_ENDPOINT	No	Custom S3 endpoint (required for R2)
S3_BUCKET	No	S3 bucket name (default: preel-videos)

Scripts

npm run typecheck        # TypeScript check
npm run dev              # Remotion Studio (local)
npm run build            # Bundle Remotion project
npm run docker:build     # Build Docker image
npm run docker:server    # Start webhook server in Docker
npm run docker:preview   # Render preview video with default props
npm run docker:review    # Review a PR via CLI in Docker

License

MIT