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 --versiondevuelve 3.11 o superior -
neo --helpresponde - El
.envtiene al menos una API key -
CROWDAR_SKILLS_DIRapunta a una carpeta con subcarpetaslippia-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_serversenqa-stack.yaml