Problem
Automate the first review pass for Python PRs without flooding authors with warnings from unchanged code. Results should appear inside GitHub and remain available for history.
Back to projects
Code Review Bot
A GitHub App for Python Pull Request review. It analyses changed lines only, combines Ruff with GigaChat insights, stores the result, and publishes a structured PR comment.
- Integration
- GitHub App and webhooks
- Analysis
- Ruff + GigaChat
- Execution
- FastAPI · Celery · PostgreSQL
PROBLEM & CONSTRAINTS
A webhook must return quickly while review remains useful during AI outages.
The system sits across several external services and separates event acceptance from heavy diff analysis.
Constraints
- The GitHub webhook must be HMAC-verified before a task is queued.
- Ruff and AI should focus on changed lines rather than the entire repository.
- GitHub API and GigaChat can fail temporarily.
- Review rules must be configurable per connected repository.
ARCHITECTURE
Event intake is separated from analysis and publication.
FastAPI verifies the webhook and queues a Celery task. The worker fetches the diff, runs Ruff and GigaChat, persists the review, and publishes through the GitHub API.
- HMAC verification
- exponential backoff
- Ruff fallback
- persisted reviews
REVIEW FLOW
Review is produced as a reproducible pipeline.
Each step has a separate responsibility: event trust, diff retrieval, static analysis, AI enrichment, and publication.
Webhook verification
FastAPI validates the GitHub HMAC signature and rejects events that cannot be tied to a trusted sender.
Background task dispatch
The HTTP handler does not perform review synchronously; event data is delegated to Celery through Redis.
Diff and configuration retrieval
The worker fetches changed lines and reads .codereview.yml from the PR branch, applying select, ignore, and exclude rules.
Ruff and GigaChat
Ruff produces deterministic findings, while GigaChat adds architecture, security, and refactoring recommendations.
Persistence and publication
The result is stored in PostgreSQL and published as a structured Pull Request comment; a short Telegram notification is optional.
KEY DECISIONS
AI augments deterministic analysis rather than replacing it.
The architecture preserves a useful result even when the external AI dependency partially fails.
HMAC before processing
The webhook signature is checked at ingress, so an untrusted event never reaches the task queue.
Diff-scoped review
The bot focuses on PR lines instead of repeating the repository's entire accumulated technical debt.
Graceful Ruff fallback
A GigaChat outage reduces review depth but does not stop baseline static analysis.
.codereview.yml from the PR branch
Teams can change rules alongside code without restarting the service or sharing one global configuration.
QUALITY & DELIVERY
The project includes code, migrations, tests, and a production pipeline.
The repository documents the path from a local Docker environment to a GHCR image and VPS deployment.
Unit tests use pytest, pytest-asyncio, and mocks to isolate GitHub and AI integrations.
GitHub App installations, repositories, and review results are persisted in PostgreSQL with schema migrations.
The workflow runs tests, builds a container, publishes the image, and deploys it over SSH.
TRADE-OFFS
Review quality depends on diff context and external APIs.
The system reduces integration risk without hiding the limits of AI-assisted review.
AI remains an external dependency
When GigaChat is unavailable, Ruff still runs, but architecture and semantic recommendations become more limited.
GitHub token cache is process-local
The cache is simple and fast, but horizontal scaling would require a shared store or coordinated refresh strategy.
Deployment requires secret management
The GitHub App key, webhook secret, AI credentials, and SSH access must stay outside the repository and be reviewed regularly.
RESULT
The bot turns a PR event into a controlled asynchronous process.
The key outcome is a resilient combination of deterministic tooling and AI: Ruff provides a baseline signal, while GigaChat adds context when available.
- An AI integration needs a clear fallback and should not be the product's only source of value.
- Webhook handlers should acknowledge quickly and move heavy work into a queue.
- Changed-line review improves relevance and reduces noise for Pull Request authors.
SOURCE CODE
The repository contains the complete path from webhook to PR comment.
The README documents local setup, GitHub App configuration, .codereview.yml, Docker, migrations, and CI/CD.