> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raigal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Control de calidad en pull requests y seguimiento en el panel

> Comprobaciones en pull requests, integración con GitHub App, protección de ramas y seguimiento en el tablero.

Configura Raigal para evaluar pull requests en GitHub, aplicar protección de ramas y supervisar el estado de cada cambio en el panel web de [app.raigal.dev](https://app.raigal.dev).

## Arquitectura: GitHub App y Actions

Raigal combina la GitHub App oficial (`raigal-cloud`) con tus flujos de trabajo de GitHub Actions:

```text theme={null}
┌───────────────────────────────┐        ┌───────────────────────────────┐
│     Repositorio de GitHub     │        │       Raigal Cloud            │
│                               │        │                               │
│  Un desarrollador abre un PR  │───────►│ 1. GitHub App recibe evento   │
│  (Head SHA: 3b2a1c...)        │        │    (pull_request.opened)      │
│                               │        │                               │
│  El runner de Actions inicia  │        │                               │
│  (ejecuta npx raigal ci)      │        │                               │
│          │                    │        │                               │
│          ▼ (POST /v1/runs)    │        │ 2. Crea check pendiente       │
│   Ingesta de métricas y SHA   │───────►│    "Raigal Quality Gate"      │
│                               │        │                               │
│                               │        ▼                               │
│                               │◄─────── Actualiza el check run         │
│                               │         (Éxito / Fallo + Resumen)      │
│                               │        │                               │
│  Protección de ramas aplicada │        │                               │
│  Tarjeta actualizada en vivo  │        │                               │
└───────────────────────────────┘        └───────────────────────────────┘
```

Funcionamiento de este modelo:

* **Análisis de código en local**: La evaluación de reglas se ejecuta íntegramente en el runner de CI. Raigal Cloud no clona ni almacena tu código.
* **Comprobación pendiente de inmediato**: Al abrir o actualizar un PR, la app registra una comprobación `"Raigal Quality Gate"` en estado `in_progress` en el commit correspondiente.
* **Actualización con resumen**: Cuando el runner envía los resultados a `/v1/runs`, Raigal Cloud empareja el commit SHA y publica un informe markdown completo.
* **Protección de ramas**: Puedes marcar `"Raigal Quality Gate"` como requisito obligatorio en las reglas de ramas de GitHub.
* **Actualización automática al fusionar o cerrar**: GitHub envía los eventos directamente a la app, actualizando el tablero sin scripts adicionales.
* **Tiempo límite de seguridad**: Si un trabajo de CI se cancela o falla antes de ejecutar `raigal ci`, Raigal Cloud limpia automáticamente las comprobaciones pendientes tras 20 minutos para no bloquear pull requests.

## Configuración: GitHub App y Actions

**1. 1. Instala la GitHub App de Raigal**

1. Abre la [GitHub App oficial de Raigal](https://github.com/apps/raigal-cloud).
2. Pulsa en **Install**.
3. Elige tu organización o cuenta personal de GitHub.
4. Selecciona todos los repositorios o los que quieras proteger.
5. Confirma con **Install & authorize**.

**2. 2. Obtén el token de la organización**

1. Entra en tu panel en [app.raigal.dev](https://app.raigal.dev).
2. Abre **Settings**.
3. En **API Tokens**, pulsa en **Create new token**.
4. Asigna un nombre al token (por ejemplo: `ci-runner`) y copia la clave generada (`rgl_live_...`).

**3. 3. Guarda el secreto en el repositorio**

1. En tu repositorio de GitHub, ve a **Settings** > **Secrets and variables** > **Actions**.
2. Pulsa en **New repository secret**.
3. Nombre: `RAIGAL_TOKEN`.
4. Valor: pega la clave `rgl_live_...`.
5. Guarda con **Add secret**.

> [!NOTE]
>
> Si no deseas gestionar claves estáticas, configura `permissions: id-token: write` en tu flujo. Raigal Cloud autenticará al runner mediante OIDC criptográfico de GitHub.

**4. 4. Añade el flujo de GitHub Actions**

Crea el archivo `.github/workflows/raigal.yml` en tu repositorio:

```yaml theme={null}
name: Raigal quality gate

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main, master, develop]
  push:
    branches: [main, master, develop]

jobs:
  quality-gate:
    name: Code quality gate
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write

    steps:
      - name: Descargar código
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Historial completo necesario para diffs

      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Ejecutar control de calidad
        env:
          RAIGAL_TOKEN: ${{ secrets.RAIGAL_TOKEN }}
          # RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }} # Requerido solo si el propietario pertenece a varias organizaciones
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            git fetch origin ${{ github.base_ref }} --depth=1
            npx --yes @methiu/raigal@latest ci --changes --base origin/${{ github.base_ref }}
          else
            npx --yes @methiu/raigal@latest ci .
          fi
```

> [!NOTE]
>
> Como la GitHub App recibe los eventos de cierre directamente, no necesitas ningún flujo extra para notificar a Raigal cuando se cierra un PR.

**5. 5. Activa el estado obligatorio en la protección de ramas**

1. En tu repositorio de GitHub, entra en **Settings** > **Branches** (o **Rules > Rulesets**).
2. En las reglas de tu rama principal (`main`), activa **Require status checks to pass before merging**.
3. Busca y marca **Raigal Quality Gate**.
4. Guarda los cambios.

## Veredictos del control de calidad (3 estados)

Las comprobaciones en pull requests devuelven tres estados claros:

| Veredicto de estado | Criterio | Resultado en GitHub |
| - | - | - |
| **PASSED** | Nota >= umbral (por defecto 70), 0 errores, 0 advertencias | `success` (Aprobado limpio) |
| **PASSED (WITH WARNINGS)** | Nota >= umbral (por defecto 70), 0 errores, advertencias presentes | `neutral` (Aprobado informativo, no bloquea el merge) |
| **FAILED / BLOCKED** | Nota \< umbral (por defecto 70), código distinto de 0 o errores presentes | `failure` (Bloquea la fusión) |

## Modo CI independiente (sin GitHub App)

Si las políticas de tu empresa impiden instalar aplicaciones de GitHub de terceros, puedes usar Raigal únicamente con GitHub Actions:

**1. 1. Configura el secreto**

En **Settings** > **Secrets and variables** > **Actions**, añade `RAIGAL_TOKEN`.

**2. 2. Añade el flujo de trabajo**

Crea `.github/workflows/raigal.yml` con el archivo YAML anterior. En modo independiente, el resultado se notifica como un paso habitual de Actions.

**3. 3. Añade la sincronización de cierre (opcional)**

Para actualizar el tablero al cerrar ramas sin la GitHub App, añade este flujo:

```yaml theme={null}
name: Sincronización de PRs

on:
  pull_request:
    types: [closed]

jobs:
  sync-pr-closed:
    name: Sincronizar estado de PR cerrada
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Notificar cierre a Raigal Cloud
        env:
          RAIGAL_TOKEN: ${{ secrets.RAIGAL_TOKEN }}
          RAIGAL_API_URL: ${{ secrets.RAIGAL_API_URL || 'https://app.raigal.dev' }}
        run: |
          npx --yes @methiu/raigal@latest report-pr-closed \
            --pr ${{ github.event.pull_request.number }} \
            ${{ github.event.pull_request.merged && '--merged' || '' }}
```

## Seguimiento de PRs en el panel web

En [Raigal Cloud](https://app.raigal.dev), abre el panel de tu proyecto:

1. **Columna de pull requests**:
   * Aprobados: muestra la nota obtenida (por ejemplo: `94/100`), autor, rama origen y rama destino.
   * Bloqueados: muestra el número de problemas críticos y categorías de reglas que han fallado.
2. **Panel de inspección lateral**:
   * Pulsa sobre una tarjeta para abrir su vista detallada.
   * Revisa las reglas incumplidas, archivos y líneas exactas.
   * Revisa las estadísticas del diff y la previsualización del parche unificado.
   * Copia el comando `git checkout` para revisar los cambios en local o pulsa **Open on GitHub** para ir directo al pull request.

## Resolución de incidencias

| Síntoma | Causa probable | Solución |
| - | - | - |
| `ambiguous_organization` (HTTP 400) | La cuenta propietaria del repositorio pertenece a varias organizaciones | En el flujo de CI, añade `RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }}` con tu ID de organización (`org_...`) de [Settings](https://app.raigal.dev/settings). |
| La comprobación se queda en estado pendiente | El flujo de CI no se ejecutó o falló antes de lanzar `raigal ci` | Comprueba que el trabajo de Actions se ejecutó para el commit head. Raigal Cloud descarta comprobaciones pendientes huérfanas tras 20 minutos. |
| La comprobación no aparece en el PR | La GitHub App no está instalada en el repositorio | Comprueba que la [GitHub App raigal-cloud](https://github.com/apps/raigal-cloud) esté instalada en la cuenta u organización correspondiente. |
| Error HTTP 401 Unauthorized en CI | Falta el secreto `RAIGAL_TOKEN` o ha expirado | Comprueba que `RAIGAL_TOKEN` esté guardado en los secretos de GitHub y coincida con un token activo de [Settings](https://app.raigal.dev/settings). |
| Error HTTP 403 `owner_not_allowed` en CI | El propietario del repositorio no está vinculado en Raigal | Ve a **Settings > Allowed Owners** en Raigal Cloud y pulsa **Sync GitHub**. |
| La vista previa del diff muestra 0 archivos | Clonado superficial (`fetch-depth: 1`) | Añade `fetch-depth: 0` en `actions/checkout@v4` para disponer del historial git completo. |
| La tarjeta del PR no se actualiza al fusionar | Modo independiente sin flujo de sincronización | Si trabajas sin la GitHub App, añade el flujo de trabajo `report-pr-closed`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.