> ## 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.

# Organización

> Guía de puesta en marcha para equipos, administradores y pilotos en Raigal Cloud.

Esta guía explica cómo configurar Raigal para tu equipo utilizando el panel web en [app.raigal.dev](https://app.raigal.dev) y la [GitHub App oficial de Raigal](https://github.com/apps/raigal-cloud).

Raigal ayuda a equipos de desarrollo a detectar problemas generados por asistentes de código (Claude Code, Cursor, Copilot, OpenCode). Las organizaciones nuevas disponen de 14 días de prueba de evaluación con acceso completo a los seis motores de análisis, comprobaciones automáticas en pull requests y el panel de seguimiento.

## Resumen de configuración

| Paso | Acción | Dónde | Tiempo |
| - | - | - | - |
| 1. Crear organización | Inicia sesión con GitHub, Google o correo de empresa | [app.raigal.dev](https://app.raigal.dev) | 1 min |
| 2. Instalar GitHub App | Conecta la app a los repositorios elegidos | [github.com/apps/raigal-cloud](https://github.com/apps/raigal-cloud) | 1 min |
| 3. Copiar token de API | Copia tu clave `rgl_live_...` | Configuración > Tokens de API | 30 seg |
| 4. Añadir flujo de CI | Añade `.github/workflows/raigal.yml` | Repositorio | 2 min |
| 5. Verificar primer escaneo | Abre un pull request o haz push a main | GitHub | 1 min |
| 6. Invitar al equipo | Invita a tus compañeros | Configuración > Miembros | 1 min |

## 1. Crea el espacio de trabajo de tu organización

1. Entra en [app.raigal.dev](https://app.raigal.dev).
2. Inicia sesión con GitHub, Google o tu correo corporativo.
3. Abre el menú de organizaciones en la esquina superior derecha y selecciona **Crear organización** (o entra en una existente).
4. Escribe el nombre de tu empresa u organización (por ejemplo: `Acme Corp`).
5. Tu espacio de trabajo se creará al instante con 14 días de prueba activos.

> [!NOTE]
>
> Si gestionas varios equipos o entornos de prueba, puedes cambiar de organización en cualquier momento desde el selector superior derecho.

## 2. Instala la GitHub App de Raigal

La [GitHub App de Raigal](https://github.com/apps/raigal-cloud) conecta tus repositorios con el panel en la nube. Crea comprobaciones pendientes al abrir o actualizar pull requests, actualiza el estado al terminar el análisis en CI y mantiene al día el tablero cuando las ramas se fusionan o cierran.

1. En el panel de Raigal Cloud, ve a **Settings** y pulsa en **Sync GitHub accounts** (o entra directamente en [github.com/apps/raigal-cloud](https://github.com/apps/raigal-cloud)).
2. Pulsa en **Install app**.
3. Selecciona tu organización o cuenta personal de GitHub.
4. Elige **All repositories** o selecciona únicamente los repositorios que quieras revisar.
5. Confirma con **Install & authorize**.

Tras la instalación, GitHub registra tu cuenta bajo **Settings > Allowed Owners** en Raigal Cloud, autorizando las ejecuciones de CI de esos repositorios.

## 3. Obtén el token de API de tu organización

Para que los runners de GitHub Actions o tus terminales locales puedan enviar métricas al panel:

1. Entra en [app.raigal.dev/settings](https://app.raigal.dev/settings).
2. En la sección **API Tokens**, busca la tarjeta **Active organization token** y copia tu clave (`rgl_live_...`).
3. Para crear una clave propia para CI, pulsa **Create new token**, dale un nombre reconocible (por ejemplo: `github-actions-ci`) y copia el token generado.

> [!WARNING]
>
> Los tokens de API se muestran completos una sola vez al generarse. Guárdalo en un lugar seguro. Raigal Cloud solo guarda el hash SHA-256 y no puede recuperar claves perdidas.

> [!NOTE]
>
> En GitHub Actions también puedes usar autenticación sin secretos fijando `permissions: id-token: write` en el flujo. Raigal Cloud valida al runner mediante tokens criptográficos OIDC de GitHub. Aun así, configurar `RAIGAL_TOKEN` en GitHub Secrets garantiza máxima compatibilidad multiplataforma.

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

Añade el archivo `.github/workflows/raigal.yml` a tu repositorio:

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

on:
  push:
    branches: [main, master, develop]
  pull_request:
    branches: [main, master, develop]

permissions:
  contents: read
  id-token: write        # Autenticación OIDC criptográfica sin secretos fijos
  security-events: write # Necesario si exportas informes SARIF a GitHub Code Scanning

jobs:
  quality-gate:
    name: Code quality gate
    runs-on: ubuntu-latest

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

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

      - name: Generar informe de seguridad SARIF (opcional)
        if: always()
        run: npx --yes @methiu/raigal@latest scan . --sarif > raigal-results.sarif

      - name: Subir SARIF a GitHub Code Scanning (opcional)
        if: always() && github.event.pull_request.head.repo.full_name == github.repository
        uses: github/codeql-action/upload-sarif@v3
        continue-on-error: true
        with:
          sarif_file: raigal-results.sarif
          category: raigal
```

### Guarda el secreto en GitHub:

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

## 5. Comprueba tu primer análisis

Para verificar que la integración funciona de principio a fin:

1. **Escaneo en pull request**: Abre un pull request en tu repositorio.
   * La GitHub App de Raigal crea al instante una comprobación pendiente llamada **Raigal quality gate**.
   * El runner de GitHub Actions ejecuta `raigal ci --changes --base origin/<base>`.
   * La comprobación termina con un resumen con la nota (0-100), el número de incidencias y el desglose de reglas.
   * Aparece la tarjeta correspondiente en tu panel de Raigal Cloud en la pestaña **Pull Requests**.
2. **Escaneo en la rama principal**: Haz push de un commit a `main` (o fusiona el pull request).
   * El flujo ejecuta un escaneo completo (`raigal ci .`).
   * La nota base del repositorio y los problemas activos se actualizan en las pestañas **Errors** y **Warnings** de [app.raigal.dev](https://app.raigal.dev).

## 6. Invita a tu equipo

1. En Raigal Cloud, ve a **Settings** > **Members**.
2. Pulsa en **Invite member** y escribe el correo de tu compañero.
3. Elige el rol:
   * **Admin**: Control total para vincular repositorios, tokens de API, facturación y miembros.
   * **Member**: Acceso para ver repositorios, inspeccionar incidencias y revisar pull requests.
4. Tu compañero recibirá un correo con el enlace para unirse al espacio de trabajo.

## Configuración local para desarrolladores

Los desarrolladores pueden ejecutar escaneos y correcciones automáticas en su máquina antes de subir código:

```bash theme={null}
# Inicia sesión desde el terminal mediante el navegador
npx @methiu/raigal login

# Comprueba la organización activa y repositorios autorizados
npx @methiu/raigal whoami

# Verifica las herramientas locales y motores instalados
npx @methiu/raigal doctor

# Lanza un escaneo local completo
npx @methiu/raigal scan .

# Aplica correcciones automáticas seguras
npx @methiu/raigal fix .

# Instala los hooks de intercepción para asistentes
npx @methiu/raigal hook install --claude
```

## Resolución de incidencias habituales

| Síntoma | Causa probable | Solución |
| - | - | - |
| `ambiguous_organization` (HTTP 400) | La cuenta de GitHub está vinculada a más de una organización en Raigal | En tu flujo de CI, define `RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }}` con el ID de tu organización (`org_...`) disponible en [Settings](https://app.raigal.dev/settings). |
| `owner_not_allowed` (HTTP 403) | El propietario del repositorio no está vinculado a tu organización en Raigal | En Raigal Cloud, ve a **Settings > Allowed Owners** y pulsa **Sync GitHub**, o asegúrate de haber instalado la GitHub App en esa cuenta. |
| Comprobación atascada en `in_progress` | El flujo de CI falló antes de ejecutar `raigal ci` o el archivo YAML no existe | Revisa que `.github/workflows/raigal.yml` haya corrido para el commit del PR. Raigal Cloud descarta automáticamente comprobaciones huérfanas tras 20 minutos. |
| Error HTTP 401 Unauthorized en CI | Falta el secreto `RAIGAL_TOKEN` o no es válido | Comprueba que `RAIGAL_TOKEN` esté guardado en los secretos de GitHub y coincida con un token activo en [Settings > API Tokens](https://app.raigal.dev/settings). |
| La vista previa del diff muestra 0 archivos | Clonado superficial (shallow clone) en Actions | Añade `fetch-depth: 0` en el paso `actions/checkout@v4` para que el runner tenga el historial git completo contra la rama base. |


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