Nirik documentation

Table of Contents

1. Overview
2. Features
3. How It Works
4. Prerequisites
5. Quick Start
6. Self-Hosting
7. Configuration
8. Webhook Setup
9. Webhook Security
10. Metrics Security
11. API Reference
12. Project-Specific Rules
13. Operations
14. Troubleshooting
15. FAQ

Overview

Nirik is a self-hosted AI code review service for GitHub pull requests and GitLab merge requests. When PR/MR events arrive by webhook, Nirik fetches the diff, filters noisy files, and sends full hunk context (unchanged context, removed, and added lines) to the AI so reviews are accurate. It posts comments only on added lines. By default the AI outputs a summary and errors (and warnings); info/suggestion-level comments are included only when your project rules request them.

Think of it as a reviewer who never sleeps, never bikesheds variable names for 40 minutes, and never says "LGTM" without context.

Features

• Supports GitHub PR webhooks and GitLab MR webhooks.
• Single webhook endpoint for both providers.
• Uses Gemini or OpenAI for AI review generation.
• Sends full hunk context (context + removed + added lines) to the AI for accurate reviews; comments are posted only on added lines.
• Default: summary and errors (and warnings) only; info/suggestions when project rules request them (e.g. in .nirik/rules.md).
• Background processing with queue workers for fast webhook responses.
• Prometheus metrics endpoint with token protection.
• Works on Docker Compose or Node process deployment.

How It Works

1. GitHub/GitLab sends webhook to POST /api/v1/webhooks/review-pr.
2. Nirik verifies request signature/token (if configured).
3. Nirik validates event action and enqueues review job.
4. Worker fetches diff using Git provider API.
5. Review engine filters files and chunks full hunks (context + removed + added lines); comments are attached only to added lines.
6. AI generates summary + line comments (default: summary and errors/warnings only unless rules request info/suggestions).
7. Nirik posts comments/discussions back to PR/MR.

Prerequisites

• Node.js 20+ (for non-Docker runs).
• Redis service available for queue/worker runtime.
• At least one AI key: Gemini or OpenAI.
• At least one Git provider token: GitHub and/or GitLab.

Quick Start

Goal: first useful review in minutes, not by the next sprint planning meeting.

Option A: Docker Compose

git clone https://github.com/imabhinavdev/nirik.git
cd nirik
cp .env.example .env
# edit .env
docker compose up -d

Option B: Local Node

git clone https://github.com/imabhinavdev/nirik.git
cd nirik
pnpm install
cp .env.example .env
# edit .env
pnpm start

Self-Hosting

Production rule of thumb: if it can fail at 3 a.m., it eventually will. Set health checks and logs before it does.

1. Run Nirik behind HTTPS using Nginx, Caddy, Traefik, or Cloudflare Tunnel.
2. Set BASE_URL to your public domain in .env.
3. Expose endpoint /api/v1/webhooks/review-pr publicly.
4. Protect secrets and rotate provider tokens regularly.
5. Keep logs/monitoring enabled for job and API health.

Configuration

Set values in .env before starting the app.

Webhook Setup

GitHub

1. Repo Settings -> Webhooks -> Add webhook.
2. Payload URL: https://your-domain.com/api/v1/webhooks/review-pr.
3. Content type: application/json.
4. Events: Pull requests.
5. Set Secret and mirror it in GITHUB_WEBHOOK_SECRET.

GitLab

1. Project Settings -> Webhooks.
2. URL: https://your-domain.com/api/v1/webhooks/review-pr.
3. Enable Merge request events.
4. Set Secret token and mirror it in GITLAB_WEBHOOK_TOKEN.
5. For self-hosted GitLab, set GITLAB_URL.

Webhook Security

• GitHub requests are validated using HMAC SHA-256 signature header.
• GitLab requests are validated using token header comparison.
• If secrets are not set, webhook verification is disabled and not production-safe.

Metrics Security

GET /metrics requires an authorization header.

Authorization: Bearer <METRICS_TOKEN>

Example request:

curl -H "Authorization: Bearer your_token" https://your-domain.com/metrics

If you expose metrics publicly without auth, the internet will benchmark your mistakes for free.

API Reference

Project-Specific Rules

Add a .nirik/rules.md file in the target repository branch to apply custom review instructions. If not present, default prompt rules are used.

By default the AI outputs only a summary and error/warning findings. To receive info or suggestion-level comments, mention that in your rules (e.g. include words like "suggestions", "info", or "hints").

Operations

• Use process supervision for Node deployments (systemd/PM2).
• Monitor logs for provider API failures and queue backlogs.
• Scrape metrics securely with METRICS_TOKEN.
• Rotate API tokens and webhook secrets periodically.

Troubleshooting

• Missing Git tokens: set GITHUB_TOKEN and/or GITLAB_TOKEN.
• Missing AI keys: set GEMINI_API_KEY or OPENAI_API_KEY.
• 401 on webhook: verify configured webhook secret/token matches provider settings exactly.
• 401 on metrics: send Authorization: Bearer <METRICS_TOKEN>.
• No review after 202: inspect logs for AI or provider API errors and queue worker activity.

Debugging sequence: logs, env, webhook delivery history, then coffee. In that order.

FAQ

Can I use both Gemini and OpenAI?

Yes. If both keys are set, Gemini is selected first.

Can I use self-hosted GitLab?

Yes. Set GITLAB_URL to your instance base URL.

Does it review every event?

No. It processes review-relevant open/update event actions only.

Can I run this without Docker?

Yes. Install dependencies and run the Node server directly.

Why only summary and errors by default?

To keep reviews focused. Info and suggestion-level comments are enabled when your .nirik/rules.md asks for them (e.g. by mentioning "suggestions" or "info").

Will this end code review debates forever?

No, but it will move debates from "did anyone review this?" to "should this be a utility function?" which is real progress.