Saltar a contenido

Requisitos e instalación

El engine se puede ejecutar de tres formas. Elegí la que corresponda a tu caso:

Forma Cuándo usarla Qué necesitás
Local Probar un plan, escribir uno nuevo, depurar Python, el repo del engine y el de skills (ver punto 1)
Docker Ejecutar igual que en el CI, sin instalar Python Docker (ver punto 2)
CI Que se ejecute solo ante un evento del repositorio La configuración del pipeline (ver punto 3)

1. Ejecutarlo en tu computadora

1.1 Qué tiene que estar instalado

Requisito Versión Para qué
Python 3.11 o superior El engine está escrito en Python
Git Cualquiera reciente Clonar los repositorios
Node.js 20 o superior Solo si el plan usa el navegador (tools: [browser]) o ejecuta una suite Playwright
uv (uvx) Cualquiera reciente Solo si el proyecto usa Jira: el MCP de Jira se lanza con uvx mcp-atlassian
Una API key Anthropic u OpenAI Los modelos que usa el plan

1.2 Repositorios

El engine no trae las skills adentro: las lee de una carpeta. Lo más simple es clonar los dos repositorios uno al lado del otro:

mis-repos/
├── crowdar-engine-mvp/     ← el engine
├── neo-releases/           ← las skills (el engine las busca en ../neo-releases/skills)
└── mi-proyecto/            ← el repositorio de pruebas, con su qa-stack.yaml

1.3 Instalación

Desde la carpeta crowdar-engine-mvp:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
copy .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Para comprobar que quedó instalado:

neo --help

1.4 El archivo .env

El engine lee su configuración de variables de entorno, o de un archivo .env en la carpeta desde donde lo ejecutás. El .env está en .gitignore: nunca se commitea.

Variable Obligatoria Para qué
ANTHROPIC_API_KEY Si el plan usa modelos anthropic/... Llamar a Claude
OPENAI_API_KEY Si el plan usa modelos openai/... Llamar a GPT
CROWDAR_SKILLS_DIR No (default ../neo-releases/skills) Dónde están las skills
CROWDAR_ANTHROPIC_MODEL No Modelo de Anthropic que usa el Modelo 2 para clasificar, si no se pasa --model
CROWDAR_OPENAI_MODEL No Ídem, para OpenAI

Ejemplo:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
CROWDAR_SKILLS_DIR=../neo-releases/skills

Espacios y saltos de línea en las keys

Si pegás una API key con un espacio o un salto de línea al final (pasa seguido en PowerShell), el engine lo limpia solo al arrancar. No hace falta editarla a mano.

1.5 El repositorio de pruebas

El engine trabaja dentro de la carpeta del repositorio de pruebas que le indicás con --workspace. Esa carpeta tiene que tener:

Archivo Para qué Cómo se genera
qa-stack.yaml Le dice al engine qué framework y qué CI usa el proyecto, dónde van los tests, los planes y los reportes, y qué servidores MCP lanzar Con la skill lippia-neo-bootstrap-stack
.env.tests (u otro, según paths.env_file) URL y credenciales de la app bajo test Lo crea el bootstrap; se completa a mano
plans/*.yaml Los planes que se van a ejecutar Se copian del repo del engine o se escriben (ver Anatomía de un plan)

1.6 Si el plan usa Jira o Azure DevOps

Fuera de Claude Code no se usa .mcp.json. El engine lanza los servidores MCP con los comandos de la sección mcp_servers de qa-stack.yaml, y las credenciales las toma de las variables de entorno del proceso:

# qa-stack.yaml (sin credenciales: esas van en el entorno)
mcp_servers:
  jira:
    command: uvx
    args: [mcp-atlassian]
  azure-devops:
    command: npx
    args: ["-y", "@tiberriver256/mcp-server-azure-devops"]
Proveedor Variables de entorno
Jira JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN (y CONFLUENCE_* si aplica)
Azure DevOps AZURE_DEVOPS_ORG_URL, AZURE_DEVOPS_AUTH_METHOD (pat), AZURE_DEVOPS_PAT, AZURE_DEVOPS_DEFAULT_PROJECT (opcional)

Para dejarlas guardadas de forma permanente en tu computadora, ver Requisitos y puesta en marcha.


2. Ejecutarlo con Docker

El engine se publica como imagen en el Container Registry de GitLab de Crowdar. Hay dos variantes:

Imagen Qué trae Cuándo usarla
crowdar-engine-mvp:latest El engine (Python 3.11), git y uv Planes que solo razonan sobre archivos (sin navegador)
crowdar-engine-mvp:latest-playwright Lo anterior + Node.js 22 + el navegador del MCP de Playwright Planes que exploran la app (tools: [browser]) o ejecutan una suite Playwright

La imagen trae solo el engine: ni skills, ni planes, ni credenciales. Esas tres cosas se le pasan al ejecutarla:

docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e CROWDAR_SKILLS_DIR=/skills/skills \
  -v "$PWD/../neo-releases:/skills:ro" \
  -v "$PWD:/work" -w /work \
  <registry>/lippia/products/neo/crowdar-engine-mvp:latest \
  run plans/feature-new-end-to-end.yaml --input-file input.json --workspace /work

Fijá la versión de la imagen

latest cambia con cada merge a la rama principal del engine. Para ejecuciones reproducibles, usá una etiqueta fija (por ejemplo c4cd2740-playwright, la que usan hoy los templates de CI).


3. Ejecutarlo en el CI

En el CI no hay que instalar nada: el job usa la imagen del engine, clona las skills y ejecuta el plan. Los archivos del pipeline los genera la skill lippia-neo-ci-bootstrap. Todo el detalle (variables, labels, diferencias entre plataformas) está en Configurar el CI.

Soporte de plataformas

Los comandos neo event y neo report (leer el evento del MR/PR y comentar el resultado) soportan hoy GitLab y GitHub. Bitbucket y Jenkins no tienen adapter de CI en el engine.


4. Checklist rápido

  • python --version devuelve 3.11 o superior
  • neo --help responde
  • El .env tiene al menos una API key
  • CROWDAR_SKILLS_DIR apunta a una carpeta con subcarpetas lippia-neo-*
  • El repositorio de pruebas tiene qa-stack.yaml
  • Si el plan usa navegador: Node.js instalado (o imagen -playwright)
  • Si el plan usa Jira o Azure DevOps: variables de entorno cargadas y mcp_servers en qa-stack.yaml