GitHub

Детальний гайд для інтеграції з GitHub Actions.

---

Permissions

Мінімальні права

permissions:
  contents: read        # Читати код
  pull-requests: write  # Писати коментарі

GITHUB_TOKEN в Actions

В GitHub Actions автоматично доступний GITHUB_TOKEN:

env:
  GITHUB_TOKEN: ${{ github.token }}

Права автоматичного токену:

Право	Статус	Примітка
contents: read		За замовчуванням
pull-requests: write		Потрібно вказати в permissions

Fork PRs

Для PR з fork репозиторіїв GITHUB_TOKEN має лише read права.

AI Review не зможе постити коментарі для fork PRs.

Як отримати Personal Access Token

Для локального запуску потрібен Personal Access Token (PAT):

1. Перейдіть до Settings → Developer settings → Personal access tokens
2. Оберіть Fine-grained tokens (рекомендовано) або Classic
3. Натисніть Generate new token

Fine-grained token (рекомендовано):

Налаштування	Значення
Repository access	Only select repositories → ваш репозиторій
Permissions	Pull requests: Read and write

Classic token:

Scope	Опис
repo	Повний доступ до репозиторію

1. Натисніть Generate token
2. Скопіюйте токен та збережіть як GITHUB_TOKEN

Збережіть токен

GitHub показує токен лише один раз. Збережіть його одразу.

---

Triggers

Рекомендований trigger

on:
  pull_request:
    types: [opened, synchronize, reopened]

Тип	Коли спрацьовує
opened	PR створено
synchronize	Нові коміти в PR
reopened	PR відкрито знову

Фільтрація по файлах

Запускати review тільки для певних файлів:

on:
  pull_request:
    paths:
      - '**.py'
      - '**.js'
      - '**.ts'

Фільтрація по гілках

on:
  pull_request:
    branches:
      - main
      - develop

---

Secrets

Додавання секретів

Settings → Secrets and variables → Actions → New repository secret

Secret	Обов'язковий	Опис
AI_REVIEWER_GOOGLE_API_KEY		Gemini API ключ

Використання

env:
  AI_REVIEWER_GOOGLE_API_KEY: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

Ніколи не хардкодьте секрети

# ❌ НЕПРАВИЛЬНО
env:
  AI_REVIEWER_GOOGLE_API_KEY: AIza...

# ✅ ПРАВИЛЬНО
env:
  AI_REVIEWER_GOOGLE_API_KEY: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

---

Workflow приклади

Мінімальний

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

Про GITHUB_TOKEN

secrets.GITHUB_TOKEN — це автоматичний токен, який GitHub створює для кожного workflow run. Його не потрібно додавати в secrets вручну — він вже доступний.

Права токена визначаються секцією permissions у workflow файлі.

GitHub Docs: Automatic token authentication

З concurrency (рекомендовано)

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}
          language: uk
          language_mode: adaptive

Що робить concurrency:

• Якщо новий коміт пушиться поки review ще йде — старий review скасовується
• Економить ресурси та API calls

З фільтрацією fork PRs

jobs:
  review:
    runs-on: ubuntu-latest
    # Не запускати для fork PRs (немає доступу до secrets)
    if: github.event.pull_request.head.repo.full_name == github.repository

---

GitHub Action inputs

Input	Опис	Default
google_api_key	Gemini API ключ	required
github_token	GitHub токен	${{ github.token }}
language	Мова відповідей	en
language_mode	Режим мови	adaptive
gemini_model	Модель Gemini	gemini-2.5-flash
log_level	Рівень логування	INFO
review_max_comment_chars	Макс. символів коментаря MR у промпті	3000
review_include_bot_comments	Включати коментарі ботів у промпт	true
review_post_inline_comments	Публікувати inline коментарі до рядків	true
gemini_model_fallback	Ланцюжок fallback-моделей (через кому)	gemini-3-flash-preview
review_enable_dialogue	Групувати коментарі в діалоги	true
discovery_enabled	Увімкнути project discovery	true
discovery_verbose	Завжди публікувати discovery коментар	false
discovery_timeout	Таймаут discovery в секундах	30

Змінні оточення

Action передає inputs у змінні оточення AI_REVIEWER_* внутрішньо. При запуску поза Action використовуйте змінні AI_REVIEWER_* напряму (старі назви, наприклад GOOGLE_API_KEY, все ще працюють як fallback).

---

Конфігурація через Variables

Використовуйте Repository Variables для перемикання між LLM-провайдерами та моделями без зміни workflow файлу. Це зручно для порівняння якості рев'ю різних моделей на одному PR.

Налаштування

Secrets (задати один раз):

Secret	Опис
AI_REVIEWER_GOOGLE_API_KEY	Gemini API ключ
AI_REVIEWER_MISTRAL_API_KEY	Mistral API ключ

Variables (Settings → Secrets and variables → Actions → Variables):

Variable	Опис	Default
LLM_PROVIDER	Основний провайдер (google, mistral)	google
LLM_FALLBACK_PROVIDER	Fallback-провайдер	(немає)
MISTRAL_MODEL	Модель Mistral	mistral-large-latest
MISTRAL_API_URL	Кастомний URL API (для Codestral free tier)	(немає)

Workflow

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}
          mistral_api_key: ${{ secrets.AI_REVIEWER_MISTRAL_API_KEY }}
          llm_provider: ${{ vars.LLM_PROVIDER || 'google' }}
          llm_fallback_provider: ${{ vars.LLM_FALLBACK_PROVIDER || '' }}
          mistral_model: ${{ vars.MISTRAL_MODEL || 'mistral-large-latest' }}
          mistral_api_url: ${{ vars.MISTRAL_API_URL || '' }}

Перемикання пресетів

Змініть Variables в GitHub UI, потім Re-run workflow на тому ж PR:

Пресет	LLM_PROVIDER	MISTRAL_MODEL	MISTRAL_API_URL	LLM_FALLBACK_PROVIDER
Gemini (за замовчуванням)	google	(немає)	(немає)	(немає)
Mistral Large	mistral	mistral-large-latest	(немає)	google
Codestral free	mistral	codestral-latest	https://codestral.mistral.ai	google
Devstral	mistral	devstral-latest	(немає)	google

Ключ для Codestral free tier

Для пресету "Codestral free" AI_REVIEWER_MISTRAL_API_KEY має містити ключ з codestral.mistral.ai, а не з console.mistral.ai.

Variables vs Secrets

Secrets — зашифровані, приховані в логах — для API ключів. Variables — видимі в логах — для несекретних налаштувань (назви моделей).

---

Результат review

Inline comments

AI Review публікує коментарі безпосередньо до рядків коду:

• CRITICAL — критичні проблеми (security, bugs)
• WARNING — рекомендації
• INFO — навчальні нотатки

Apply Suggestion

Кожен коментар з пропозицією коду має кнопку "Apply suggestion":

fixed_code_here

GitHub автоматично рендерить це як інтерактивну кнопку.

Summary

В кінці review публікується Summary з:

• Загальною статистикою issues
• Метриками (час, токени, вартість)
• Good practices (позитивний фідбек)

---

Troubleshooting

Review не постить коментарі

Перевірте:

1. permissions: pull-requests: write є в workflow
2. AI_REVIEWER_GOOGLE_API_KEY секрет встановлено
3. PR не з fork репозиторію

"Resource not accessible by integration"

Причина: Недостатньо прав.

Рішення: Додайте permissions:

permissions:
  contents: read
  pull-requests: write

Rate limit від Gemini

Причина: Перевищено ліміт free tier (15 RPM).

Рішення:

• Зачекайте хвилину
• Додайте concurrency для скасування старих runs
• Розгляньте paid tier

---

Best practices

1. Завжди використовуйте concurrency

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

2. Фільтруйте fork PRs

if: github.event.pull_request.head.repo.full_name == github.repository

3. Встановіть timeout

jobs:
  review:
    timeout-minutes: 10

4. Зробіть job non-blocking

jobs:
  review:
    continue-on-error: true

---

Наступний крок

• GitLab інтеграція →
• CLI Reference →