Integración con CI

Verica se integra con CI al revés que la mayoría de las herramientas de evals. El eval vive en Verica — el golden set, los criterios, los jueces, la condición de aprobación. El repositorio solo tiene el prompt. CI no define la evaluación: la dispara por ID.

La consecuencia práctica es que el único secreto que tu pipeline necesita es el token de Verica. No hay que inyectar OPENAI_API_KEY en el runner.

Crear un token

En Configuración del proyecto → API Keys: "Tokens para disparar evals de este proyecto desde tu CI/CD. El token se muestra una sola vez al crearlo."

El diálogo pide un Nombre (por ejemplo ci-github) y los Permisos:

Para CI hacen falta run y read, que vienen marcados por defecto.

El token tiene la forma vk_live_… y se muestra una sola vez: "Guárdalo ahora: no se vuelve a mostrar." Verica guarda solo su hash y un prefijo visible, así que la lista te deja identificarlo sin poder recuperarlo.

Guárdalo en tu CI como VERICA_TOKEN. Puedes revocarlo cuando quieras — "El token dejará de funcionar de inmediato en tu CI/CD."

El CLI

npx @verica-app/cli run --eval eval_8x2k9d --prompt prompts/agente.txt --junit report.xml

El paquete es @verica-app/cli, MIT, requiere Node 20 o superior y expone un único comando: run.

Variables de entorno

• VERICA_TOKEN — obligatoria.
• VERICA_BASE_URL — solo para instalaciones propias o desarrollo. Por defecto https://my.verica.app.

Opciones

Qué ejecutar

Resultado y gate

Reutilización

Procedencia y transporte

--git-sha, --git-ref y --git-repo-url se deducen solos de las variables de GitHub Actions o GitLab; sirven para que la ejecución enlace al commit y a la rama. --poll-interval (3 s), --timeout (1800 s) y --base-url completan la lista.

Códigos de salida

Con varios evals, el CLI devuelve el peor de todos.

Una ejecución sin condición de aprobación definida sale con 0 y un aviso por stderr: "no pass condition defined; gating disabled (exit 0)". Si quieres que CI bloquee, define el gate.

Estos tres códigos son estables. El resto de la superficie del CLI — flags, formato JSON, salida JUnit — todavía se está asentando: el paquete es 0.x y ahí el que rompe es el minor. Conviene fijar "@verica-app/cli": "~0.1".

La condición de aprobación

El gate se configura en la interfaz, en la pestaña Configuración del eval, no en YAML. "Define cuándo una ejecución por CI 'pasa' y desbloquea el merge. Vacía → las ejecuciones siempre pasan."

Son tres dimensiones que se combinan con Y:

El panel resume la condición en una frase: "Pasa si: pass rate ≥ 90% y no baja más de 2 pts vs. la última ejecución en la rama base y 0 errores de ejecución."

El veredicto se calcula en el servidor cuando la ejecución termina y queda congelado con ella. El CLI no lo recalcula: lo lee.

Formatos de salida

JUnit

--junit-mode rows (por defecto) emite un caso de prueba por caso del golden set: los que no pasaron son failure, los N/A son skipped.

--junit-mode gate emite un caso por dimensión del gate, con mensajes como pass rate 94.0% vs. min 90.0%.

JSON

--json escribe un array en stdout, un elemento por eval, con runId, resultUrl, status, passed, gated, totals, gateResult, model y judge. Es un contrato público, congelado por tests.

El resumen legible va a stderr, así que stdout queda limpio para canalizarlo:

→ 50 casos · judge=rubric+llm · model=gpt-4.1-mini
✓ 47 passed  ✗ 3 failed   score 0.91

Ejemplos por plataforma

on: { pull_request: { paths: ['prompts/**'] } }
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: verica-app/run-action@v1
        with:
          token: ${{ secrets.VERICA_TOKEN }}
          manifest: .verica.yml

      - uses: verica-app/run-action@v1
        with:
          token: ${{ secrets.VERICA_TOKEN }}
          eval: eval_8x2k9d
          prompt: prompts/support-agent.txt
          model: gpt-4.1-mini
          baseline-ref: main

verica:
  image: node:22
  rules: [{ changes: ['prompts/**'] }]
  script:
    - npx @verica-app/cli run --manifest .verica.yml --junit report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

jobs:
  verica:
    docker: [{ image: cimg/node:22.0 }]
    steps:
      - checkout
      - run: npx @verica-app/cli run --manifest .verica.yml --junit report.xml
      - store_test_results: { path: report.xml }

pipeline {
  agent { docker { image 'node:22' } }
  environment {
    VERICA_TOKEN = credentials('verica-token')
  }
  stages {
    stage('eval') {
      steps { sh 'npx @verica-app/cli run --manifest .verica.yml --junit report.xml' }
    }
  }
  post { always { junit 'report.xml' } }
}

El prompt: cómo viaja y cómo se versiona

El CLI lee los archivos y manda su contenido en el cuerpo de la petición. Los tres campos son independientes y opcionales, y lo que no mandes se hereda de la versión actual: pasar solo --system-prompt versiona el prompt de sistema y deja intactos los mensajes y las herramientas.

Del lado del servidor:

1. Se combinan los campos enviados sobre la versión actual.
2. Se compara el contenido resultante. Si es idéntico, se reutiliza la versión; si no, se crea una nueva.
3. El modelo y los parámetros de sampling no entran en esa comparación — viajan en la ejecución. Cambiar solo el modelo reutiliza la versión del prompt y crea una ejecución nueva.
4. Siempre se encola una ejecución. El deduplicado decide si nace una versión, nunca si se ejecuta.

La respuesta trae el número de versión y si fue nueva, y el CLI lo imprime: prompt v7, new version.

La procedencia (commit, rama, repositorio, que vino de CI) se estampa en la ejecución, no en la versión. Por eso un cambio de modelo, que reutiliza la versión, igual deja registrado su commit.

Validaciones antes de ejecutar

Verica responde 400 con un código estable, antes de gastar un token, si:

• El prompt usa una variable {{ }} que el golden set no tiene.
• El modelo no está en la tabla de precios (en CI esto sí es estricto, porque de ahí se deduce el proveedor).
• El workspace no tiene una credencial BYOK de ese proveedor en el proyecto del eval.

Prompt gestionado desde el repo

Desde Conectar con CI, en la página del eval, puedes marcar el prompt como repo-managed indicando su ruta. A partir de ahí git es la fuente de verdad y la interfaz lo muestra en solo lectura: "Repo-managed · {ruta}".

Ese mismo panel te da el snippet ya armado, con el ID del eval y la URL base.

Varios prompts: .verica.yml

evals:
  - id: eval_8x2k9d
    prompt: prompts/support-agent.txt
    systemPrompt: prompts/support-system.txt
    model: gpt-4.1-mini
  - id: eval_3n7q1p
    prompt: prompts/router.txt
    tools: prompts/router-tools.json

Solo id es obligatorio en cada entrada. tools acepta una ruta o un array en línea. --model desde la línea de comandos sobreescribe el de todas las entradas.

Reutilizar ejecuciones

--reuse-if-unchanged evita pagar dos veces por lo mismo. Verica considera que nada cambió cuando coinciden la versión del prompt, el modelo, los parámetros de sampling, el snapshot del dataset y los graders. El gate no forma parte de esa comparación.

Solo se reutilizan ejecuciones completadas, nunca parciales ni fallidas, y por defecto de las últimas 24 horas (máximo 720). No existe un "para siempre" a propósito: la reutilización no puede ver la deriva del proveedor detrás de un identificador de modelo estable.

Cuando hay reutilización, la API responde 200 en lugar de 202, el CLI marca reused: true, y el evento aparece en el historial del eval con la insignia reutilizada. Sin eso, una reutilización sería invisible.

La API

Si prefieres no usar el CLI, son tres endpoints:

La autenticación es Authorization: Bearer <token>. Los errores son 401 missing_token, 401 invalid_token, 403 insufficient_scope y 403 project_forbidden.

GET /runs/:id/results devuelve también la configuración congelada de los criterios que calificaron — pero solo la de los criterios determinísticos. Las configuraciones de los jueces llevan consignas y no se exponen.

Siguientes pasos

• El Eval — cómo se versiona el prompt.
• Ejecuciones y comparación — cómo se leen los totales.