GitHub

Guía detallada para integración con GitHub Actions.

---

Permisos

Permisos Mínimos

permissions:
  contents: read        # Leer código
  pull-requests: write  # Publicar comentarios

GITHUB_TOKEN en Actions

En GitHub Actions, GITHUB_TOKEN está disponible automáticamente:

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

Permisos automáticos del token:

Permiso	Estado	Nota
contents: read		Por defecto
pull-requests: write		Debe especificarse en permissions

PRs de Forks

Para PRs de repositorios fork, GITHUB_TOKEN tiene permisos de solo lectura.

AI Review no puede publicar comentarios para PRs de forks.

Cómo Obtener un Personal Access Token

Para ejecuciones locales, necesitas un Personal Access Token (PAT):

1. Ve a Settings → Developer settings → Personal access tokens
2. Elige Fine-grained tokens (recomendado) o Classic
3. Haz clic en Generate new token

Fine-grained token (recomendado):

Configuración	Valor
Repository access	Only select repositories → tu repositorio
Permissions	Pull requests: Read and write

Classic token:

Scope	Descripción
repo	Acceso completo al repositorio

1. Haz clic en Generate token
2. Copia el token y guárdalo como GITHUB_TOKEN

Guarda el token

GitHub muestra el token solo una vez. Guárdalo inmediatamente.

---

Triggers

Trigger Recomendado

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

Tipo	Cuándo se dispara
opened	PR creado
synchronize	Nuevos commits en el PR
reopened	PR reabierto

Filtrado de Archivos

Ejecutar revisión solo para archivos específicos:

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

Filtrado de Ramas

on:
  pull_request:
    branches:
      - main
      - develop

---

Secretos

Añadir Secretos

Settings → Secrets and variables → Actions → New repository secret

Secreto	Requerido	Descripción
AI_REVIEWER_GOOGLE_API_KEY		Clave API de Gemini

Uso

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

Nunca hardcodees secretos

# ❌ INCORRECTO
env:
  AI_REVIEWER_GOOGLE_API_KEY: AIza...

# ✅ CORRECTO
env:
  AI_REVIEWER_GOOGLE_API_KEY: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

---

Ejemplos de Workflow

Mínimo

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 }}

Sobre GITHUB_TOKEN

secrets.GITHUB_TOKEN es un token automático que GitHub crea para cada ejecución del workflow. No necesitas añadirlo manualmente a los secretos — ya está disponible.

Los permisos del token se definen en la sección permissions del archivo workflow.

GitHub Docs: Automatic token authentication

Con Concurrencia (recomendado)

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

Qué hace la concurrencia:

• Si se hace push de un nuevo commit mientras la revisión aún está en ejecución — la revisión anterior se cancela
• Ahorra recursos y llamadas a la API

Con Filtrado de PRs de Forks

jobs:
  review:
    runs-on: ubuntu-latest
    # No ejecutar para PRs de forks (sin acceso a secretos)
    if: github.event.pull_request.head.repo.full_name == github.repository

---

Inputs de GitHub Action

Input	Descripción	Por defecto
google_api_key	Clave API de Gemini	requerido
github_token	Token de GitHub	${{ github.token }}
language	Idioma de respuesta	en
language_mode	Modo de idioma	adaptive
gemini_model	Modelo Gemini	gemini-2.5-flash
log_level	Nivel de log	INFO
review_max_comment_chars	Máx. caracteres de comentario MR en el prompt	3000
review_include_bot_comments	Incluir comentarios de bots en el prompt	true
review_post_inline_comments	Publicar comentarios inline en líneas	true
gemini_model_fallback	Cadena de modelos de respaldo (separados por comas)	gemini-3-flash-preview
review_enable_dialogue	Agrupar comentarios en diálogos	true
discovery_enabled	Activar project discovery	true
discovery_verbose	Publicar siempre comentario de discovery	false
discovery_timeout	Tiempo de espera de discovery en segundos	30

Variables de entorno

La Action mapea los inputs a variables de entorno AI_REVIEWER_* internamente. Al ejecutar fuera de la Action, usa las variables AI_REVIEWER_* directamente (los nombres antiguos como GOOGLE_API_KEY siguen funcionando como fallback).

---

Configuración mediante Variables

Use Repository Variables para cambiar entre proveedores LLM y modelos sin modificar el archivo de workflow. Esto es útil para comparar la calidad de revisión de diferentes modelos en el mismo PR.

Configuración

Secrets (configurar una vez):

Secret	Descripción
AI_REVIEWER_GOOGLE_API_KEY	Clave API de Gemini
AI_REVIEWER_MISTRAL_API_KEY	Clave API de Mistral

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

Variable	Descripción	Predeterminado
LLM_PROVIDER	Proveedor principal (google, mistral)	google
LLM_FALLBACK_PROVIDER	Proveedor de respaldo	(ninguno)
MISTRAL_MODEL	Modelo Mistral	mistral-large-latest
MISTRAL_API_URL	URL API personalizada (para Codestral free tier)	(ninguno)

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 || '' }}

Cambiar presets

Cambie las Variables en la interfaz de GitHub y ejecute de nuevo (Re-run) el workflow en el mismo PR:

Preset	LLM_PROVIDER	MISTRAL_MODEL	MISTRAL_API_URL	LLM_FALLBACK_PROVIDER
Gemini (predeterminado)	google	(vacío)	(vacío)	(vacío)
Mistral Large	mistral	mistral-large-latest	(vacío)	google
Codestral free	mistral	codestral-latest	https://codestral.mistral.ai	google
Devstral	mistral	devstral-latest	(vacío)	google

Clave de Codestral free tier

Para el preset "Codestral free", AI_REVIEWER_MISTRAL_API_KEY debe contener una clave de codestral.mistral.ai, no de console.mistral.ai.

Variables vs Secrets

Secrets — cifrados, ocultos en logs — para claves API. Variables — visibles en logs — para configuración no sensible (nombres de modelos).

---

Resultado de la Revisión

Comentarios en Línea

AI Review publica comentarios directamente en las líneas de código:

• CRITICAL — problemas críticos (seguridad, bugs)
• WARNING — recomendaciones
• INFO — notas educativas

Apply Suggestion

Cada comentario con sugerencia de código tiene un botón "Apply suggestion":

fixed_code_here

GitHub renderiza esto automáticamente como un botón interactivo.

Resumen

Al final de la revisión, se publica un Resumen con:

• Estadísticas generales de problemas
• Métricas (tiempo, tokens, costo)
• Buenas prácticas (feedback positivo)

---

Solución de Problemas

La Revisión No Publica Comentarios

Verifica:

1. permissions: pull-requests: write está en el workflow
2. El secreto AI_REVIEWER_GOOGLE_API_KEY está configurado
3. El PR no es de un repositorio fork

"Resource not accessible by integration"

Causa: Permisos insuficientes.

Solución: Añade permisos:

permissions:
  contents: read
  pull-requests: write

Rate Limit de Gemini

Causa: Se excedió el límite del nivel gratuito (15 RPM).

Solución:

• Espera un minuto
• Añade concurrency para cancelar ejecuciones anteriores
• Considera el nivel de pago

---

Mejores Prácticas

1. Siempre usa concurrencia

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

2. Filtra PRs de forks

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

3. Establece timeout

jobs:
  review:
    timeout-minutes: 10

4. Haz el job no bloqueante

jobs:
  review:
    continue-on-error: true

---

Siguiente Paso

• Integración con GitLab →
• Referencia CLI →