К содержимому
Блог

Бот для ревью PR на LLM: код и GitHub Actions

Бот для ревью PR на LLM: код и GitHub Actions

Бот для ревью PR на LLM начинается не с промпта, а с границ. Он должен читать только доступный ему diff, не получать секреты из журнала CI и публиковать комментарий лишь тогда, когда ответ можно проверить по строке кода.

Коротко

  • Отделите получение diff, запрос к модели и публикацию комментария в разные шаги.

  • Передавайте в модель маленькие фрагменты и требуйте машинно-проверяемый JSON.

  • Храните ключ в секрете CI, задайте ему отдельные ограничения и не запускайте бота от непроверенных входных данных.

Каркас workflow

Workflow лучше запускает короткий скрипт репозитория, а не содержит всю логику в YAML. Тогда обработку ответа можно тестировать локально, а изменение правила ревью не требует читать несколько десятков строк shell-команд.

yaml
name: pr-llm-review

on:
  pull_request_target:
    types: [labeled, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    if: contains(github.event.pull_request.labels.*.name, 'llm-review-approved')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.base.sha }}
          persist-credentials: false
      - name: Review diff through API
        run: node scripts/review-pr.mjs
        env:
          RELAY_API_KEY: ${{ secrets.RELAY_API_KEY_REVIEW }}
          PR_NUMBER: ${{ github.event.pull_request.number }}

Этот вариант запускается только после метки, которую ставит сопровождающий репозитория. Runner берёт скрипт из точного SHA базовой ветки, а review-pr.mjs получает diff через API по номеру PR. Код из ветки pull request не попадает в checkout и не выполняется в job с секретом. Не передавайте ключ в аргументах команды и не печатайте переменные окружения при отладке.

Ключ создайте специально для автоматизации. В кабинете ключей можно ограничить набор моделей, запросы в минуту, срок работы и расход. Если ключ придётся отозвать, это не остановит локальные инструменты разработчиков. Критерии выбора модели для такой проверки разобраны в статье как выбрать модель для кода.

Разрежьте diff до запроса

Не отправляйте модели весь pull request одной строкой. Сначала исключите lock-файлы, минифицированный код, двоичные изменения и каталоги, где комментарии не нужны. Затем разбейте оставшийся diff по файлам и по разумным фрагментам. Каждый фрагмент несёт путь, номера новых строк, описание задачи и короткие правила модуля.

У бота две полезные роли. Первая ищет риск: пропущенная проверка прав, неверная граница транзакции, отсутствие обработки ошибки. Вторая проверяет вывод первой: есть ли нужная строка в diff, следует ли последствие из кода, не дублирует ли комментарий уже найденную ошибку CI. Публикация идёт только после обеих ролей.

Формат ответа должен быть простым. Вот пример, который легко проверить перед публикацией:

json
{
  "findings": [
    {
      "path": "server/orders/update.ts",
      "line": 84,
      "condition": "запрос повторяется после сетевой ошибки",
      "risk": "создаются две одинаковые записи",
      "check": "добавить тест с повторным вызовом",
      "confidence": "high"
    }
  ]
}

Скрипт обязан проверить схему, существование файла и строки. Отсутствует хотя бы одно поле, находка остаётся в логах job, но не появляется в обсуждении PR.

Вызов модели без магии

Для текстового ревью достаточно обычного формата Chat Completions. Перед первым запуском сверяйте идентификатор модели в каталоге, а адрес и заголовок, в документации по аутентификации. Пример ниже намеренно не вшивает название модели в репозиторий.

js
const response = await fetch('https://relay-llm.ru/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.RELAY_API_KEY}`,
  },
  body: JSON.stringify({
    model: process.env.REVIEW_MODEL,
    messages: [
      { role: 'system', content: 'Верни JSON по указанной схеме. Не пиши комментарий без строки и проверки.' },
      { role: 'user', content: reviewInput },
    ],
  }),
})

if (!response.ok) throw new Error(`review request failed: ${response.status}`)
const payload = await response.json()
const text = payload.choices?.[0]?.message?.content

До вызова задайте REVIEW_MODEL в конфигурации CI. Так обновление модели не превращается в поисковую замену по workflow. Не добавляйте в промпт цену или обещание скорости: данные каталога меняются, а стоимость запроса удобнее смотреть по факту.

Как публиковать комментарий

Модель не должна формировать разметку API для площадки. Пусть она отдаёт только структурированные поля. Скрипт сам строит текст комментария, добавляет ссылку на строку и ставит постоянный маркер, например <!-- llm-review -->. При повторном запуске он обновляет свой прежний комментарий или создаёт новый тред, но не плодит одинаковые сообщения.

Текст нужен короткий. Сначала условие сбоя, затем последствие, потом проверка. Вместо «здесь возможна ошибка» пишите: «после повторного запроса запись создаётся второй раз; добавьте тест с тем же идентификатором». Если точной правки нет, не вставляйте suggestion: человек прочтёт её как готовое исправление.

В больших diff бот может вернуть десятки черновиков. Введите потолок публикации, а остальные поместите в одну сводку job. Это снижает шанс, что второстепенная находка закроет важную проверку в ленте.

Контролируйте расход и сбои

Цена ревью PR складывается из объёма контекста, числа фрагментов и повторных проходов. Фактический расход считайте как C = Σ c_i, где c_i это списание каждого вызова из журнала. Для планирования подойдёт C = F × P × c_avg, где F это число фрагментов, P число проходов, а c_avg средняя стоимость сопоставимых прошлых запросов. Это оценка: контекст, ответ, кэш и модель меняют цену отдельных вызовов.

Записывайте в лог job номер PR, имя ключа, выбранную модель и x-request-id. В журнале запросов можно сверить время, модель, статус, токены и расход. Если Relay ответил временной ошибкой, смотрите x-should-retry и Retry-After; правила ограниченных повторов описаны в разделе лимитов.

Нельзя считать отказ модели пустым ревью. Job должен явно завершаться статусом, который команда отличит от ответа «находок нет». Иначе самый дорогой класс ошибок, бот промолчал из-за сбоя, будет выглядеть как зелёный результат.

Проверьте бота на трёх видах pull request

До включения на всей организации возьмите небольшой учебный репозиторий. В первом pull request положите реальную ошибку в изменённую строку. Во втором оставьте безопасный рефакторинг без находок. В третьем добавьте большой diff, который бот обязан сократить до сводки. Эти три случая проверяют точность, молчание в нормальном сценарии и защиту от перегрузки.

Для каждого запуска сохраните входной фрагмент и итог скрипта, но не секреты. Затем сравните опубликованный комментарий с тем, что увидел ревьюер. Если бот указывает на строку вне diff, это ошибка валидатора. Если строка есть, но последствие выдумано, меняйте инструкцию и контекст. Такие причины нельзя смешивать в одну метрику «бот ошибся».

Отдельно проверьте повторный запуск на том же SHA. Он не должен создавать вторую копию комментария. Ещё один важный сценарий, изменение pull request после первого ревью: старое замечание либо помечается устаревшим, либо обновляется на новой строке. Молчаливый перенос старой ссылки вводит автора в заблуждение.

Не превращайте бота в тайного владельца качества

Скрипт не должен принимать решение о слиянии и менять код в ветке автора. Его роль, принести проверяемый сигнал. Обязательные правила остаются обычными джобами CI, а ревьюер отвечает за контекст продукта и архитектуры.

Хорошая граница видна в интерфейсе. У комментария есть маркер автоматизации и ссылка на исходный job. Автор может ответить фактом или закрыть вопрос после правки. Команда видит, что вывод пришёл от бота, и не приписывает модели полномочия, которых у неё нет.

Держите текст diff отдельно от инструкции

Разделяйте системные правила, описание задачи и фрагмент кода явными блоками. Это снижает шанс, что строка из diff повлияет на ход рассуждения, но не отменяет проверок. Пользовательский текст, комментарии и имена файлов тоже рассматривайте как данные, а не как инструкции.

Перед публикацией проверьте, что модель не вернула фрагмент входного diff в комментарии без причины. Такой фильтр уменьшает риск случайно вынести служебный текст в публичное обсуждение. Комментарий должен содержать только нужную строку, условие сбоя и проверку.

Нужно ли публиковать все замечания модели?

Нет. Публикуйте только находки с файлом, строкой, условием сбоя и проверкой. Остальные сохраняйте в сводке job, чтобы настроить промпт и фильтры без шума в pull request. Комментарий без способа проверки не помогает автору и быстро приучает команду игнорировать бота.

Где хранить ключ бота?

В хранилище секретов CI. Не кладите его в код, конфигурацию репозитория или текст комментария. Для бота используйте отдельный ключ с ограничениями, а при подозрении на утечку перевыпустите его. Лог job должен скрывать значение секрета, даже если запрос завершился ошибкой.

Что нужно проверить после ответа модели?

Проверьте схему ответа, разрешённые файлы и строки, допустимый объём комментария и полномочия токена публикации. Затем отфильтруйте находки по правилам репозитория. Разделение входных блоков полезно, но безопасный результат создаёт только код, который валидирует ответ перед внешним действием.

Создать аккаунт для бота ревью

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.