Задача
Автоматизировать первичное review Python PR без спама предупреждениями по старому коду. Результат должен появляться в привычном интерфейсе GitHub и сохраняться для истории.
Назад к проектам
Code Review Bot
GitHub App для review Python Pull Request. Бот анализирует только изменённые строки, объединяет Ruff с AI-инсайтами GigaChat, сохраняет результат и публикует структурированный комментарий в PR.
- Интеграция
- GitHub App и webhooks
- Анализ
- Ruff + GigaChat
- Исполнение
- FastAPI · Celery · PostgreSQL
PROBLEM & CONSTRAINTS
Webhook должен отвечать быстро, а review — оставаться полезным при сбоях AI.
Система работает на границе нескольких внешних сервисов и должна отделять приём события от тяжёлого анализа diff.
Ограничения
- GitHub webhook необходимо проверить по HMAC до постановки задачи.
- Ruff и AI должны анализировать изменённые строки, а не весь репозиторий без контекста.
- GitHub API и GigaChat могут временно быть недоступны.
- Правила review должны настраиваться отдельно для каждого подключённого репозитория.
ARCHITECTURE
Приём события отделён от анализа и публикации результата.
FastAPI проверяет webhook и ставит задачу в Celery. Воркер получает diff, запускает Ruff и GigaChat, сохраняет review в PostgreSQL и публикует комментарий через GitHub API.
- HMAC verification
- exponential backoff
- Ruff fallback
- persisted reviews
REVIEW FLOW
Review формируется как воспроизводимый pipeline.
Каждый шаг имеет отдельную ответственность: доверие к событию, получение diff, статический анализ, AI-обогащение и публикация.
Проверка webhook
FastAPI сверяет HMAC-подпись GitHub и отклоняет события, которые нельзя связать с доверенным отправителем.
Постановка фоновой задачи
HTTP-обработчик не выполняет review синхронно: данные события передаются Celery через Redis.
Получение diff и конфигурации
Воркер получает изменённые строки и читает .codereview.yml из ветки PR, применяя select, ignore и exclude.
Ruff и GigaChat
Ruff даёт детерминированные замечания, а GigaChat добавляет рекомендации по архитектуре, безопасности и рефакторингу.
Сохранение и публикация
Результат сохраняется в PostgreSQL и публикуется структурированным комментарием в Pull Request; краткое уведомление может уйти в Telegram.
KEY DECISIONS
AI дополняет детерминированный анализ, а не заменяет его.
Архитектура сохраняет полезный результат даже при частичном отказе внешней AI-зависимости.
HMAC до обработки
Подпись webhook проверяется на входе, поэтому недоверенное событие не попадает в очередь задач.
Diff-scoped review
Бот фокусируется на строках PR и не повторяет автору весь накопленный технический долг репозитория.
Graceful fallback на Ruff
Недоступность GigaChat снижает глубину review, но не останавливает базовый статический анализ.
.codereview.yml в ветке PR
Правила можно менять рядом с кодом без перезапуска сервиса и глобальной конфигурации для всех команд.
QUALITY & DELIVERY
Проект включает код, миграции, тесты и production pipeline.
Репозиторий документирует путь от локального Docker-окружения до сборки образа в GHCR и развёртывания на VPS.
Unit-тесты используют pytest, pytest-asyncio и mocks для изоляции GitHub и AI-интеграций.
Установки GitHub App, репозитории и результаты review сохраняются в PostgreSQL с миграциями схемы.
Workflow запускает тесты, собирает контейнер, публикует образ и выполняет deployment через SSH.
TRADE-OFFS
Полезность review зависит от качества diff и внешних API.
Система снижает риски, но не пытается скрыть ограничения AI и интеграционной архитектуры.
AI остаётся внешней зависимостью
При недоступности GigaChat review продолжается на Ruff, но рекомендации по архитектуре и семантике становятся ограниченнее.
Кэш GitHub-токенов находится в памяти процесса
Такой кэш прост и быстр, но при горизонтальном масштабировании потребует общего хранилища или согласованной стратегии обновления.
Deployment требует управления секретами
GitHub App key, webhook secret, AI credentials и SSH-доступ должны храниться вне репозитория и регулярно проверяться.
RESULT
Бот превращает PR-событие в контролируемый асинхронный процесс.
Ключевой результат — устойчивое сочетание deterministic tooling и AI: Ruff обеспечивает базовый сигнал, а GigaChat добавляет контекст там, где доступен.
- AI-интеграция должна иметь понятный fallback и не быть единственной точкой полезности продукта.
- Webhook лучше подтверждать быстро, перенося тяжёлую обработку в очередь.
- Review по изменённым строкам повышает релевантность и снижает шум для автора PR.
SOURCE CODE
Репозиторий содержит полный путь от webhook до PR-комментария.
В README описаны локальный запуск, GitHub App, .codereview.yml, Docker, миграции и CI/CD.