ИИ-ревью пул-реквестов на GitHub с помощью Yandex Workflows и GitHub Actions

В этом руководстве вы воспользуетесь возможностями моделей генерации текста Yandex AI Studio для реализации сценария автоматического ревью предлагаемых изменений в программном коде на GitHub.

Предлагаемое решение использует сценарий GitHub Actions, чтобы запросить в Yandex Cloud ИИ-ревью изменений в пул-реквесте. Процесс получения изменений, запрос формирования ревью генеративной моделью и последующая публикация ревью на GitHub выполняются рабочим процессом Yandex Workflows.

На схеме:

1. Пользователь добавляет коммит в пул-реквест на GitHub.
2. После появления нового коммита в пул-реквесте запускается сценарий GitHub Actions.
3. Сценарий GitHub Actions получает авторизованный ключ сервисного аккаунта Yandex Cloud, сохраненный в секрете репозитория на GitHub.
4. Сценарий GitHub Actions запрашивает IAM-токен в обмен на авторизованный ключ сервисного аккаунта в сервисе Yandex Identity and Access Management. IAM-токен необходим для аутентификации в API Yandex Serverless Integrations.
5. Сценарий GitHub Actions с использованием полученного IAM-токена отправляет рабочему процессу Yandex Workflows HTTP-запрос на формирование ревью. При этом в рабочий процесс Workflows передается номер пул-реквеста.
6. Рабочий процесс Workflows получает в секрете Yandex Lockbox токен доступа personal access token (classic) к репозиторию на GitHub.
7. Рабочий процесс Workflows с использованием токена доступа получает в репозитории на GitHub изменения, предлагаемые в пул-реквесте.
8. Рабочий процесс Workflows запрашивает у модели Yandex AI Studio формирование ревью изменений, предлагаемых в пул-реквесте. Модель возвращает сгенерированное ревью с комментариями и собственными предложениями по улучшению кода.
9. Рабочий процесс Workflows с использованием токена доступа публикует полученное ревью в пул-реквесте на GitHub.

Чтобы настроить автоматическое ИИ-ревью пул-реквестов на GitHub:

1. Создайте репозиторий на GitHub.
2. Подготовьте облако к работе.
3. Создайте рабочий процесс Workflows.
4. Настройте сценарий GitHub Actions.
5. Протестируйте работу сценария.

Если созданные ресурсы вам больше не нужны, удалите их.

Создайте репозиторий в GitHubСоздайте репозиторий в GitHub

Создайте на GitHub новый репозиторий или используйте существующий, в котором у вас есть права на просмотр и запуск GitHub Actions.

Создайте и сохраните токен доступа personal access token (classic) с областью доступа repo или public_repo.

Подготовьте облако к работеПодготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Необходимые платные ресурсыНеобходимые платные ресурсы

В стоимость поддержки инфраструктуры для реализации сценария автоматического ИИ-ревью пул-реквестов входят:

• плата за генерацию текста (см. тарифы Yandex AI Studio);
• плата за хранение секрета и операции с ним (см. тарифы Yandex Lockbox);
• плата за запись и хранение данных в лог-группе, если вы используете сервис Cloud Logging (см. тарифы Yandex Cloud Logging).

Создайте секрет Yandex LockboxСоздайте секрет Yandex Lockbox

Создайте секрет Yandex Lockbox, в котором будет безопасно храниться токен доступа GitHub.

yc lockbox secret create \
  --name github/pat-for-workflows \
  --payload '[{"key":"token","textValue":"<токен_доступа>"}]'

done (1s)
id: e6q034pgt99k********
folder_id: b1gt6g8ht345********
created_at: "2025-08-20T15:39:05.873Z"
name: github/pat-for-workflows
status: ACTIVE
current_version:
  id: e6quqngm8om0********
  secret_id: e6q034pgt99k********
  created_at: "2025-08-20T15:39:05.873Z"
  status: ACTIVE
  payload_entry_keys:
    - token

Создайте сервисные аккаунтыСоздайте сервисные аккаунты

Cоздайте два сервисных аккаунта:

• workflow-sa — от его имени будет выполняться рабочий процесс Workflows;
• github-worker — от его имени будет запускаться рабочий процесс при получении запроса от сценария GitHub Actions.

1. Создайте сервисный аккаунт workflow-sa и назначьте ему роли lockbox.payloadViewer и ai.languageModels.user:

   Консоль управления

   CLI

   API

   1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.
   2. В списке сервисов выберите Identity and Access Management.
   3. Нажмите кнопку Создать сервисный аккаунт.
   4. Введите имя сервисного аккаунта workflow-sa.
   5. Нажмите кнопку Добавить роль и выберите роли lockbox.payloadViewer и ai.languageModels.user.
   6. Нажмите кнопку Создать.

   1. Чтобы создать сервисный аккаунт, выполните команду:

      yc iam service-account create \
        --name workflow-sa
      

      Результат:

      done (1s)
      id: aje4rh1vb737********
      folder_id: b1gt6g8ht345********
      created_at: "2025-08-21T13:49:54.097378917Z"
      name: workflow-sa
      

      Сохраните идентификатор созданного сервисного аккаунта (значение поля id) — он понадобится позднее при назначении роли и создании рабочего процесса.

   2. Чтобы назначить созданному сервисному аккаунту роль lockbox.payloadViewer, выполните команду:

      yc resource-manager folder add-access-binding <идентификатор_каталога> \
        --role lockbox.payloadViewer \
        --subject serviceAccount:<идентификатор_сервисного_аккаунта>
      

      Где:

      • <идентификатор_каталога> — идентификатор каталога, в котором вы создаете инфраструктуру.
      • <идентификатор_сервисного_аккаунта> — сохраненный на предыдущем шаге идентификатор сервисного аккаунта.

      Результат:

      done (2s)
      effective_deltas:
        - action: ADD
          access_binding:
            role_id: lockbox.payloadViewer
            subject:
              id: aje4rh1vb737********
              type: serviceAccount
      

   3. Аналогичным образом назначьте созданному сервисному аккаунту роль ai.languageModels.user.

   Чтобы создать сервисный аккаунт, воспользуйтесь методом REST API create для ресурса ServiceAccount или вызовом gRPC API ServiceAccountService/Create.

   Чтобы назначить сервисному аккаунту роль на каталог, воспользуйтесь методом REST API updateAccessBindings для ресурса Folder или вызовом gRPC API FolderService/UpdateAccessBindings.

2. Аналогичным образом создайте сервисный аккаунт github-worker и назначьте ему роль serverless.workflows.executor.

Создайте авторизованный ключ сервисного аккаунтаСоздайте авторизованный ключ сервисного аккаунта

Создайте авторизованный ключ для сервисного аккаунта github-worker. Авторизованный ключ позволит сценарию GitHub Actions получать IAM-токен для аутентификации в API Yandex Cloud.

yc iam key create \
  --service-account-name github-worker \
  -o authorized_key.json

Создайте рабочий процесс WorkflowsСоздайте рабочий процесс Workflows

Создайте рабочий процесс Workflows на стороне Yandex Cloud.

1. Создайте файл yawl-spec.yaml со следующей YaWL-спецификацией рабочего процесса:

   yawl-spec.yaml

   yawl: '0.1'
   start: GetDiff
   steps:
     GetDiff:
       httpCall:
         url: >-
           https://api.github.com/repos/<имя_организации_на_GitHub>/<имя_репозитория>/pulls/\(.input)
         method: GET
         headers:
           Accept: application/vnd.github.v3.diff
           Authorization: Bearer \(lockboxPayload("<идентификатор_секрета>"; "token"))
         output: '\({diff: .})'
         next: Review
         catch: []
     Review:
       aiAgent:
         agentConfig:
           role: >-
             Опытный разработчик-программист, специализирующийся на ревью
             изменений в репозиториях на языке(ах) проекта.
           goal: >-
             Провести ревью diff: найти логические ошибки, уязвимости, проблемы
             со стилем, предложить улучшения и тесты.
           model:
             # Можно выбрать 'yandexgpt' или другую модель;
             name: <имя_модели>
         tasks:
           - result: >-
               Текст с комментариями для публикации на GitHub. Структура:
   
               1) Логические ошибки
               2) Потенциальные проблемы безопасности
               3) Стиль кода и мелкие замечания
               4) Предложения по тестам и рефакторингу
             description: 'Проведи ревью этих изменений: \(.diff)'
         output: '\({review: .Result})'
         next: PostComment
     PostComment:
       httpCall:
         # POST comment на issues (pull request comments проходят через issues API)
         url: >-
           https://api.github.com/repos/<имя_организации_на_GitHub>/<имя_репозитория>/issues/\(.input)/comments
         method: POST
         body: |-
           \({
             body: .review
           })
         headers:
           Authorization: Bearer \(lockboxPayload("<идентификатор_секрета>"; "token"))
           X-GitHub-Api-Version: '2022-11-28'
   

   Где:

   • <имя_организации_на_GitHub> — имя пользователя или организации — владельца репозитория на GitHub.
   • <имя_репозитория> — имя репозитория на GitHub.
   • <идентификатор_секрета> — сохраненный ранее идентификатор секрета Yandex Lockbox.
   • <имя_модели> — имя модели генерации текста Yandex AI Studio. Например: qwen3-235b-a22b-fp8.

2. Создайте рабочий процесс:

   Консоль управления

   CLI

   API

   1. В консоли управления перейдите в каталог, в котором вы создаете инфраструктуру.
   2. В списке сервисов выберите Serverless Integrations.
   3. На панели слева нажмите Workflows.
   4. В правом верхнем углу нажмите Создать рабочий процесс.
   5. Выберите способ YaML-спецификация.
   6. В редакторе кода вставьте содержимое созданного ранее файла yawl-spec.yaml.
   7. Раскройте блок Дополнительные параметры:
   8. В поле Имя укажите имя рабочего процесса. Например: github-ai-review-workflow.
   9. В поле Сервисный аккаунт выберите созданный ранее сервисный аккаунт workflow-sa.
   10. (Опционально) Настройте логирование запусков рабочего процесса.
   11. Нажмите Создать.

   В результате откроется окно с таблицей, содержащей информацию о созданном рабочем процессе. Сохраните его идентификатор — он понадобится позднее при настройке сценария GitHub Actions.

   Выполните команду:

   yc serverless workflow create \
     --yaml-spec <путь_к_файлу_спецификации> \
     --name <имя_рабочего_процесса> \
     --service-account-id <идентификатор_сервисного_аккаунта> \
     --no-logging
   

   Где:

   • --yaml-spec — путь к созданному ранее файлу с YaWL-спецификацией. Например: ./yawl-spec.yaml.
   • --name — имя создаваемого рабочего процесса. Например: github-ai-review-workflow.
   • --service-account-id — сохраненный ранее идентификатор сервисного аккаунта workflow-sa.
   • --no-logging — параметр, отключающий логирование запусков рабочего процесса. Необязательный параметр. Если параметр не задан, логи запусков рабочего процесса записываются в лог-группу по умолчанию того каталога, в котором создан рабочий процесс.

   Результат:

   done (4s)
   id: dfq58scovpo5********
   folder_id: b1gt6g8ht345********
   specification:
     spec_yaml: |-
     ...
   created_at: "2025-08-21T19:09:18.299850Z"
   name: github-ai-review-workflow
   status: ACTIVE
   log_options:
     disabled: true
   service_account_id: ajerhj18qmdd********
   

   Сохраните идентификатор созданного рабочего процесса (значение поля id) — он понадобится позднее при настройке сценария GitHub Actions.

   Чтобы создать рабочий процесс, воспользуйтесь методом REST API Create для ресурса Workflows или вызовом gRPC API WorkflowService/Create.

Настройте сценарий GitHub ActionsНастройте сценарий GitHub Actions

1. В интерфейсе GitHub создайте секрет репозитория с именем YC_SA_JSON_CREDENTIALS и скопируйте в него содержимое полученного ранее файла с авторизованным ключом.

2. Склонируйте ваш репозиторий, если это еще не сделано:

   git clone <URL_репозитория>
   

3. В локальной копии вашего репозитория создайте директорию .github/workflows/ (если еще не создана) и создайте в этой директории файл ai-review.yml.

4. В файл ai-review.yml вставьте следующий код, указав в поле workflowId сохраненный ранее идентификатор рабочего процесса Workflows:

   name: Pull Request Automated Checks
   on:
     pull_request:
       branches:
         - main
   
   jobs:
     neuro-review:
       runs-on: ubuntu-latest
       steps:
         - name: Get IAM Token (Yandex)
           id: issue-iam-token
           uses: yc-actions/yc-iam-token@v1
           with:
             # в secrets храните JSON ключ авторизованного ключа SA
             yc-sa-json-credentials: ${{ secrets.YC_SA_JSON_CREDENTIALS }}
   
         - name: Start Review Workflow
           uses: fjogeleit/http-request-action@v1
           with:
             url: 'https://serverless-workflows.api.cloud.yandex.net/workflows/v1/execution/start'
             method: 'POST'
             bearerToken: "${{ steps.issue-iam-token.outputs.token }}"
             data: |
               {
                 "workflowId": "<идентификатор_рабочего_процесса>",
                 "input": {
                   "inputJson": "${{ github.event.pull_request.number }}"
                 }
               }
   

5. Сохраните файл и отправьте изменения в удаленный репозиторий:

   git add . && git commit -m "Added ai-review.yml" && git push
   

Протестируйте работу сценарияПротестируйте работу сценария

Чтобы проверить работу сценария, создайте новый пул-реквест в вашем репозитории на GitHub. При создании пул-реквеста, а также при каждой последующей отправке в пул-реквест нового коммита будет запускаться сценарий GitHub Actions, инициирующий создание на стороне Yandex Cloud ревью предлагаемых изменений и публикацию этого ревью в пул-реквесте.

Удалите созданные ресурсыУдалите созданные ресурсы

Чтобы перестать платить за созданные ресурсы:

1. Удалите секрет Yandex Lockbox.
2. Удалите рабочий процесс Workflows.
3. Удалите лог-группу, если вы включали логирование запусков рабочего процесса.
4. При необходимости удалите сервисные аккаунты.