Yolo AI Reviewer

Automated AI code review for GitLab & GitHub — self-host it as a server, run it in Docker, or drop it straight into your CI pipeline. No vendor lock-in.

Yolo acts as a tireless, automated code reviewer. When a developer opens a Pull Request or Merge Request, Yolo fetches the diff, reads your team's custom review standards (.skills/), sends them to an AI model, and posts inline comments directly on the changed lines — exactly like a senior engineer doing a code review.

Why Yolo?

• 🔀 Multi-platform — Works with both GitLab and GitHub out of the box.
• 🧠 AI Agnostic — Bring your own AI: OpenAI, Anthropic, Gemini, or any self-hosted LLM (Ollama, etc).
• 🛡️ Skill-Based Rules — Each repository teaches Yolo what to look for via .skills/ markdown files. No hardcoded rules.
• 🌿 Per-Repo Configuration — Each repo controls its own branch filters via .yolo/config.yml.
• 📨 Telegram Alerts — Get notified for issues, LGTM, and AI errors. Supports Forum Topics.
• ✅ LGTM Detection — Post clean review when no issues found, customizable per-repo.
• 🔕 Error Alerts — Get notified on Telegram when AI fails or runs out of quota.
• 📝 Custom Templates — Customize Telegram message format globally or per-repo.
• ⚡ Skills Cache — Smart SHA-based cache prevents redundant .skills fetches.
• 🔄 Auto-Resolve — Old comments are automatically resolved when the issue is fixed in a follow-up commit.
• 🚫 Anti-Spam — Cryptographic hashing prevents duplicate comments on the same line.
• ⚡ Hot-Reload Config — Edit config.yml while the server runs — no restart needed.
• 🐳 Docker Ready — Pull directly from GHCR with a single docker compose up.

How It Works

sequenceDiagram
    actor Dev as 👨‍💻 Developer
    participant GL as 🦊 GitLab / 🐙 GitHub
    participant Yolo as ⚙️ Yolo Engine
    participant AI as 🧠 AI Model
    participant TG as 📨 Telegram

    Dev->>GL: Open / Update PR or MR

    alt Server / Docker Mode
        GL->>Yolo: Webhook event
    else CI/CD Mode
        GL->>Yolo: CI pipeline runs npx yolo-run
    end

    Yolo->>GL: Fetch .yolo/config.yml (branch filter)
    Yolo->>GL: Fetch changed file diffs
    
    Yolo->>GL: Check latest commit SHA for .skills/
    alt SHA changed or cache miss
        Yolo->>GL: Fetch .skills/*.md (review rules)
    end

    Yolo->>AI: Send diff + skill rules
    AI-->>Yolo: JSON comments (line, category, issue, suggestion)

    alt has comments
        Yolo->>GL: Post inline comments on PR/MR diff
        Yolo->>TG: Send Review Summary
    else no comments
        Yolo->>GL: Post LGTM note
        Yolo->>TG: Send LGTM message
    end

    opt AI fails
        Yolo->>TG: Send Error Alert
    end

Requirements

• Bun v1.0+ (for server/docker mode)
• GitLab or GitHub account
• An OpenAI-compatible AI endpoint (/v1/chat/completions)

Deployment Modes

Yolo can run in three different ways. Pick the one that fits your team:

| Mode | Infrastructure | Best For | | -------------------- | --------------------------- | ------------------------- | | Server (Webhook) | Your own server / VPS | Teams with multiple repos | | Docker | Docker on any server | Easy self-hosting |

Setup

Step 1 — Install & Initialize

Run the interactive CLI to generate all configuration files:

npx yolo-reviewer init

Follow the prompts:

1. Select platform: GitLab or GitHub
2. Enter credentials (token, URL, webhook secret)
3. Select AI provider and enter API key
4. Set AI model, temperature, language

Generated files:

• .env — credentials for your server
• config.yml — server-level AI behavior
• .yolo/config.yml — per-repo template (commit this to each target repo)

Step 1.5 — Setup Bot Account (Optional but Recommended)

By default, if you use your Personal Access Token (PAT) for the server, Yolo's comments will appear as if they were posted by you. To make comments appear professionally as a bot:

🐙 For GitHub

Option 1: GitHub App (⭐️ Best Practice) Using a GitHub App is the most secure and professional way. The comments will appear with the official [bot] badge (e.g., yolo-reviewer[bot]). It also scales automatically across all repos without needing a separate user account.

1. Go to your GitHub account/organization → Settings → Developer settings → GitHub Apps → New GitHub App.
2. Set the GitHub App name (e.g., Yolo Reviewer) and Homepage URL (e.g., your website).
3. Uncheck Active under the Webhook section (since we configure webhooks manually per-repo in this guide).
4. Under Repository permissions, set Pull requests to Read and write.
5. Click Create GitHub App.
6. On the next page, copy your App ID (at the top).
7. Scroll down to Private keys and click Generate a private key. A .pem file will be downloaded.
8. On the left sidebar, click Install App and install it on your selected repositories or the entire organization.
9. Instead of using GITHUB_TOKEN in your server's .env, provide these two variables:

   GITHUB_APP_ID="your_app_id"
   GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...your key...\n-----END RSA PRIVATE KEY-----\n"

   (Note: For the private key, replace actual line breaks with \n to fit on one line in the .env file).

💡 Troubleshooting Private Key Errors:
If Yolo fails to start or throws a private key parsing error (e.g., in strict Docker environments), you might need to convert your .pem file to pkcs8 format. Run this command in your terminal:
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in downloaded_key.pem -out pkcs8_key.pem
Then copy the contents of pkcs8_key.pem into your .env.

Option 2: Personal Access Token (Bot Account)

• Create a brand new GitHub account (e.g., your-company-yolo-bot).
• Invite this account to your repositories with Write access.
• Generate a PAT from this new account and put it in .env as GITHUB_TOKEN.
• Note: In CI/CD Mode (GitHub Actions), you don't need any of this. The default GITHUB_TOKEN provided by the pipeline automatically posts as github-actions[bot].

🦊 For GitLab

• Group Access Token / Project Access Token (Recommended): Go to Settings → Access Tokens at the Group or Project level. Create a token with api scope and name it Yolo Reviewer. GitLab automatically creates a background bot user with this name! Just put this token in .env as GITLAB_TOKEN.
• Service Account: Alternatively, ask your admin to create a dedicated Service Account.

Step 2A — Start the server

bun dev     # development, with hot-reload
bun start   # production

Server listens on http://localhost:3000.

Step 3A — Expose to internet

For local development, use a tunnel:

ngrok http 3000
# or
cloudflared tunnel --url http://localhost:3000

For production, deploy to a VPS and point your domain to port 3000.

Step 4A — Register webhook in GitLab

1. Go to your GitLab project → Settings → Webhooks.
2. Fill in:
   • URL: https://your-server.com/webhook/gitlab
   • Secret token: value of GITLAB_WEBHOOK_SECRET in your .env
3. Check Merge request events only. Click Add webhook.
4. Test: Click Test → Merge request events — a log should appear in your terminal.

Step 4A (alt) — Register webhook in GitHub

1. Go to your repo → Settings → Webhooks → Add webhook.
2. Fill in:
   • Payload URL: https://your-server.com/webhook/github
   • Content type: application/json
   • Secret: value of GITHUB_WEBHOOK_SECRET in your .env
3. Select Pull requests only. Click Add webhook.
4. Test: Go to Recent deliveries tab → click any delivery → Redeliver.

Step 2B — Run with Docker Compose

The Docker image ships with a built-in default config.yml — you don't need to create one just to get started. Only .env is required.

mkdir yolo-reviewer && cd yolo-reviewer

# Download the required files
curl -O https://raw.githubusercontent.com/akhfasarrofi/yolo-reviewer/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/akhfasarrofi/yolo-reviewer/main/.env.example

# Fill in your credentials (AI key, GitHub/GitLab token, etc.)
cp .env.example .env
nano .env

# Pull and start — config.yml is already built into the image
docker compose pull
docker compose up -d

# View live logs
docker compose logs -f yolo

Then follow Step 4A to register webhooks.

Optional: Customize config.yml

The default config works out of the box. To override it with your own:

# Download and edit the example
curl -O https://raw.githubusercontent.com/akhfasarrofi/yolo-reviewer/main/config.example.yml
cp config.example.yml config.yml
nano config.yml   # edit skills source, AI tuning, review instructions, etc.

Then uncomment the volume mount in docker-compose.yml:

volumes:
  - ./config.yml:/app/config.yml:ro

Restart the container to pick up the new config:

docker compose up -d

💡 Once mounted, changes to config.yml are picked up automatically (hot-reload) — no restart needed.

Update to a Newer Version

# Edit docker-compose.yml — change the image tag:
#   image: ghcr.io/akhfasarrofi/yolo-reviewer:1.3.0   ← new version

docker compose pull
docker compose up -d

Versioning is intentional — Yolo does not auto-update. Pin the version you trust and upgrade manually.

Local Testing with Webhooks (HTTPS tunnel)

GitHub and GitLab require a public HTTPS URL for webhooks. For local testing:

# Terminal 1: start the container
docker compose up -d

# Terminal 2: forward GitHub webhooks to localhost
npx smee-client --url https://smee.io/YOUR_CHANNEL --target http://localhost:3000/webhook/github
# or for GitLab:
npx smee-client --url https://smee.io/YOUR_CHANNEL --target http://localhost:3000/webhook/gitlab

Create a free channel at smee.io and use that URL as the Payload URL in your webhook settings.

Teaching Yolo What to Review (.skills/)

Yolo fetches skill files before every review and injects them into the AI prompt as your team's coding standards. There are three ways to provide skills — configure one in config.yml:

Option 1: Per-repo .skills/ (default)

Place a .skills/ folder in each repository you want reviewed:

your-project/
└── .skills/
    ├── security.md
    ├── performance.md
    └── clean-code.md

# config.yml
skillsSource:
  type: local
  path: ".skills"

Option 2: Centralized URL

Host your skills in one place (GitHub Gist, raw GitHub, CDN, etc.) and point all repos to it:

skillsSource:
  type: url
  url: https://raw.githubusercontent.com/your-org/skills/main/combined.md

Option 3: Dedicated Git Repository

Maintain a separate skills repo (your-org/yolo-skills) and fetch from it:

skillsSource:
  type: repo
  repo: your-org/yolo-skills
  branch: main
  path: skills/

Each skill file is plain markdown — write rules however you like. The filename (without .md) becomes the category the AI assigns to violations.

Example security.md:

- Never hardcode credentials, tokens, or API keys
- Always validate and sanitize user input
- Avoid exposing internal error details in API responses

If no skills are found, Yolo falls back to general best-practice review.

Per-Repo Override (.yolo/config.yml)

Place a .yolo/config.yml in each repository to override global server settings for that specific repo. Yolo fetches this file before starting the review.

# .yolo/config.yml (commit this to your target repo)
filters:
  target_branches:
    - main
    - develop

lgtm:
  message: "✅ All Good! No violations. Ready to merge! 🎉"

telegram_templates:
  review_summary: |
    🚨 *Review Done* — {{repo}} PR\#{{mr_id}}
    {{total_issues}} issues in {{file_count}} files

If this file is missing, Yolo falls back to the server's global config.yml.

Telegram Notifications

Get real-time alerts when the AI finds issues in specific categories.

Setup

1. Create a Telegram bot

• Open Telegram → search @BotFather → /newbot
• Follow the steps → copy the bot token

2. Get your chat ID

• Start a chat with your bot (send it any message)
• Open in browser: https://api.telegram.org/bot<TOKEN>/getUpdates
• Find "chat":{"id": 123456789} — that number is your chat_id

3. Configure config.yml

notifications:
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID} # Support supergroup/chat ID
    topic_id: ${TELEGRAM_TOPIC_ID}            # optional: Send to specific Forum Topic ID
    error_topic_id: ${TELEGRAM_ERROR_TOPIC_ID}      # optional: Send AI errors to a different topic

Summary & Highlights

Yolo sends 1 summary message per review. It doesn't spam you for every single issue.

Custom Templates

You can customize the Telegram message format in config.yml globally, or override it per-repo via .yolo/config.yml.

Available variables: {{repo}}, {{mr_url}}, {{mr_id}}, {{total_issues}}, {{file_count}}, {{error}}.

Server Configuration Reference (config.yml)

skillsPath: ".skills"
responseLanguage: "English" # or "Indonesian"

features:
  autoResolve: true # auto-resolve old comments when the issue is fixed
  summaryComment: true # post a summary at the end of each review
  lgtm:
    enabled: true
    message: "✅ **LGTM!** No issues found."

notifications: # optional
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID}
    topic_id: ${TELEGRAM_TOPIC_ID}
    error_topic_id: ${TELEGRAM_ERROR_TOPIC_ID}
    templates:
      review_summary: "..."
      lgtm: "..."
      error: "..."

Changes to this file are picked up immediately while the server runs.

Troubleshooting

❌ GitHub Error 403 (Forbidden)

If you see a 403 Forbidden error when Yolo tries to fetch file contents or post comments, it usually means the GitHub App doesn't have enough permissions or hasn't been properly installed on the repository.

Solution:

1. Check Permissions: Go to your GitHub App Settings → Permissions & events and ensure:
   • Contents: Read-only
   • Pull requests: Read & Write
2. Install/Configure App:
   • Go to the target Repository Settings → GitHub Apps.
   • Find your Yolo Bot App and click Configure.
   • Ensure the app is installed for the repository and any "Pending Requests" are accepted.

License

MIT