https://github.com/ambient-code/pull-reviews
https://github.com/ambient-code/pull-reviews
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ambient-code/pull-reviews
- Owner: ambient-code
- License: mit
- Created: 2026-03-12T19:43:52.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T18:37:58.000Z (3 months ago)
- Last Synced: 2026-03-21T05:25:38.548Z (3 months ago)
- Language: TypeScript
- Size: 175 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```yaml
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)
```bash
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
```bash
# 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)
```bash
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** — `` YAML blocks
See [docs/configuration.md](docs/configuration.md) for the full reference.
## Documentation
| Document | Description |
|----------|-------------|
| [Configuration](docs/configuration.md) | Full config reference — presets, YAML, env vars, auto-detection |
| [Architecture](docs/architecture.md) | System design, pipeline flow, data model |
| [Deployment](docs/deployment.md) | Docker setup, GitHub App, S3 storage, production checklist |
| [Scenes & Video](docs/scenes.md) | Video composition structure, scene details, styling |
| [CLI Reference](docs/cli.md) | Local testing commands and options |
| [LLM Analysis](docs/analysis.md) | How AI review works — prompts, providers, output format |
## Environment variables
See [`.env.example`](.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
```bash
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