Гайд · TNWS AI

Как проверять регрессии AI-промптов в pull request через GitHub Actions

19 сентября 2026 6 мин—

Практический сценарий проверки контракта AI-приложения на каждом pull request: фикстуры, unittest, workflow, диагностика и критерии приёмки.

Задача и границы применения

Остановить изменение правил маршрутизации заявок до слияния pull request, если оно ломает уже согласованный формат ответа. Команда поддержки преобразует русский текст обращения в поля priority и summary. Важно отделить проверку детерминированной подготовки данных от вероятностного ответа модели: тест без сети стабилен и доступен для PR из форка. Проверку живого сервиса лучше вынести в отдельный доверенный запуск. Ниже — сценарий для собственного репозитория, а не обещание универсальной точности генеративной модели. Для демонстрации используются вымышленные обращения, которые не содержат персональных данных.

Актуальность названий полей, событий и версий actions проверена 19.09.2026 по официальным материалам GitHub. Если у вашего проекта другая структура каталогов или другой протокол AI API, адаптируйте пути и прикладной клиент после проверки его документации. Пример не содержит утверждений о тарифах, ценах или скорости.

Что подготовить до изменения workflow

Нужен репозиторий GitHub, доступ к его Actions и возможность добавить файл в каталог .github/workflows. Подготовьте тестовую ветку и одно синтетическое обращение с известным ожидаемым результатом. Не берите production-заявки: даже если runner временный, ввод и диагностика оказываются в истории запуска. Для Python-части используйте unittest из стандартной библиотеки; если в вашем проекте есть дополнительные импорты, установите их отдельно из контролируемого файла зависимостей.

До коммита запишите контракт: какие поля обязательно должны быть в результате, какие значения разрешены и при каком несоответствии job получает ненулевой код выхода. Сначала выполните тот же скрипт локально. Это позволяет различить ошибку Python от ошибки описания workflow. Если проверка обращается к внешней модели, разделите транспортную ошибку, отсутствие ключа и несоответствие ответа: эти причины требуют разного исправления.

Пошаговая настройка

Создайте нужные каталоги и файлы из блоков ниже; имена путей в YAML должны совпадать с именами файлов в репозитории. Файл workflow хранится внутри .github/workflows, а тестовый код — в tests или scripts согласно примеру.
Проверьте три секции YAML: on задаёт событие, permissions ограничивает встроенный токен, jobs содержит runner и последовательность шагов. Не вставляйте ключи или закрытые тексты в YAML.
Сохраните тестовый файл из следующего блока, затем workflow в .github/workflows/prompt-contract.yml. В реальном проекте импортируйте функцию маршрутизации из src, а не копируйте её в тест: приведённая самодостаточная функция нужна лишь для первого проверяемого запуска. Измените обработку срочного обращения на normal и откройте PR: тест должен стать красным; верните high — зелёным. Путь paths означает, что изменение только документации не создаст этот check; если branch protection требует его всегда, уберите фильтр. Не подменяйте утверждение assertEqual сравнением всего текстового ответа модели: это другой, нестабильный уровень проверки.
Сначала воспроизведите успешный вход, затем намеренно измените одно ожидаемое значение и убедитесь, что job падает. Проверка без негативного сценария не доказывает, что тест вообще способен обнаружить регрессию. После этого верните правильное значение и повторите запуск.
При сбое откройте конкретный job и шаг, а не ориентируйтесь только на общий статус workflow. Проверьте событие запуска, выбранную ветку, наличие файлов, код завершения скрипта и последние безопасные диагностические сообщения.

Готовый шаблон workflow

Скопируйте YAML; если в блоке указаны два имени файла, разделите его на два соответствующих файла. Ссылки на внешние actions и параметры проверены по их официальным README на 19.09.2026.

name: Prompt contract PR
on:
  pull_request:
    paths:
      - 'tests/**'
      - 'src/**'
      - '.github/workflows/prompt-contract.yml'
permissions:
  contents: read
jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: python -m unittest discover -s tests -v

Код или тестовая фикстура для копирования

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

# tests/test_prompt_contract.py
import unittest

def render_ticket(text):
    # Замените на детерминированную часть своего приложения.
    # Сетевой вызов модели здесь намеренно отсутствует.
    return {"priority": "high" if "срочно" in text.lower() else "normal",
            "summary": text.strip()}

class PromptContract(unittest.TestCase):
    def test_urgent_ticket(self):
        actual = render_ticket("Срочно: платеж не прошёл")
        self.assertEqual(actual["priority"], "high")
        self.assertEqual(actual["summary"], "Срочно: платеж не прошёл")

if __name__ == "__main__":
    unittest.main()

Реалистичный вход и ожидаемый результат

Вход Срочно: платеж не прошёл даёт словарь {"priority":"high","summary":"Срочно: платеж не прошёл"}. Искусственно сломанный обработчик выдаёт normal; в логе unittest видно расхождение normal != high и job завершается неуспешно. Перед тем как трактовать красный job как баг модели, убедитесь, что сравниваются значения одной и той же ревизии кода и одной и той же фикстуры. Не подменяйте ожидаемое значение фактически полученным: такое «исправление» отключит сигнал регрессии.

Разбор ошибок и ограничения

Если workflow не появляется в Actions, сперва проверьте расположение YAML и событие on; затем проверьте ограничения по путям и веткам. Если job есть, но падает на checkout или setup-python, отличайте инфраструктурную ошибку от провала прикладного утверждения. Если Python завершился с ошибкой импорта, проверьте реальные пути и зависимости. Если проблема только в содержании ответа, сохраните минимальный безопасный вход и точное различие ожидаемого и фактического полей.

В CI тестируется выбранный контракт, а не «качество ИИ вообще». Он не доказывает отсутствие галлюцинаций, безопасность всех возможных промптов или корректность каждой интеграции. Добавляйте отдельные фикстуры для отрицательных кейсов, пустого ввода, Unicode и граничных форматов, когда эти ситуации есть в вашем продукте. Для live API ограничивайте доступ к секрету и используйте отдельные тестовые данные. Не выводите заголовки Authorization, тело закрытого ответа или переменные окружения целиком.

Чек-лист перед слиянием

Workflow лежит в .github/workflows, а событие запуска соответствует задаче.
Скрипт работает локально на синтетическом входе и падает при намеренно нарушенном контракте.
Имена файлов, переменные окружения и пути в YAML совпадают с репозиторием.
Секреты не записаны в код, входные параметры, summary или диагностический файл.
Проверен успешный запуск и понятный неуспешный запуск; просмотрен конкретный job.
Код и тесты соответствуют ограничениям доверия для внешнего PR и правам токена.
Результат относится к актуальному коммиту, а не к предыдущей ревизии.

FAQ

Почему не дергать модель в PR?

Для недоверенного кода из форка не следует раскрывать ключ API; кроме того, сетевой тест проверяет ещё доступность сервиса. Контрактную проверку держите без секретов, а интеграционную запускайте отдельно.

Как тестировать несколько формулировок?

Добавьте subTest с набором входов и ожидаемых полей, включая пустые и многострочные обращения. Каждый сценарий должен проверять конкретное инвариантное поле.

Что делать, если workflow не стартует?

Проверьте расположение файла, событие pull_request и совпадение изменённых путей с paths; затем откройте Actions и проверьте фильтры запуска.

Можно ли тестировать ответ модели дословно?

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

Как зафиксировать проверенный результат

После успешного запуска сохраните ссылку на конкретный run рядом с pull request: так ревьюер увидит проверенную ревизию. При следующем сбое сравнивайте не только цвет check, но и фикстуру, входные параметры, изменённые файлы и точный шаг ошибки. Если ослабили утверждение теста, объясните в PR, какой риск остался непокрытым, и добавьте отдельный сценарий. При переносе шаблона в другой репозиторий повторно проверьте структуру каталогов и разрешения: одинаковый YAML сам по себе не гарантирует одинаковую модель доверия. Не называйте демонстрационные результаты измерением качества или производительности AI-системы.

Официальные первоисточники

Проверено 19.09.2026. Описание синтаксиса и поведения: 1, 2, 3. Читайте первоисточники при переносе шаблона в другой репозиторий: доступность версии action или поддерживаемый синтаксис могут измениться.