Saltar al contenido principal
Soluciones para fallos habituales de compilación, respuestas a preguntas frecuentes y una guía para migrar desde la configuración interactiva heredada.
Para la configuración general del entorno, consulta configuración de Environment. Para obtener detalles de sintaxis, consulta la YAML Reference.

​
Depuración de fallos en la compilación

​
Paso 1: Comprueba el estado de la compilación

Ve a Settings > Devin’s Environment > Build History. Tu compilación mostrará uno de estos estados:
EstadoQué significaQué hacer
SuccessTodo salió bienNada — tu imagen de la máquina está lista
PartialLa compilación principal se completó correctamente, pero algunos repositorios fallaronComprueba qué repositorios fallaron; sus sesiones pueden tener problemas
FailedLa compilación fallóRevisa los registros del paso que falló
CancelledUna compilación más reciente sustituyó a estaEs normal — inicia una compilación más reciente si es necesario
SkippedNo se detectaron cambios en la configuraciónNada — no fue necesaria ninguna compilación

​
Paso 2: Lee los registros de compilación

Los registros de compilación están organizados por pasos:
  1. Configuración compartida — comandos de Enterprise y de toda la organización
  2. Clonación — clonación del repositorio
  3. Configuración del repositorio — comandos por repositorio
  4. Finalización — comprobación del estado y creación de la imagen
Busca el primer error en los registros. Los errores posteriores suelen ser fallos en cascada causados por el primero.
Si usaste la forma expandida con campos name, los registros mostrarán exactamente qué paso falló. Este es uno de los mayores beneficios de poner nombre a tus pasos: 
# Sin nombres — difícil de depurar
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# Con nombres — fácil de identificar fallos
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
Step 3: Identifica el patrón del error

​
Fallos de clonación

Síntoma: La compilación falla al clonar. Causas comunes:
  • El acceso al repositorio no está configurado — revisa Enterprise Settings > Integraciones
  • Un repositorio privado requiere un token de autenticación
  • Se cambió el nombre del repositorio o se eliminó
  • Problema de conectividad de red (se necesita una VPN o un proxy)
Solución: Verifica que Devin tenga acceso al repositorio en tu configuración de integraciones. Para registros privados, asegúrate de que las credenciales estén configuradas en Secrets.

​
Fallos en la instalación de dependencias

Síntoma: La compilación falla durante la configuración del repositorio, normalmente en npm install, pip install o comandos similares. Causas comunes:
  • Un registro privado de paquetes requiere autenticación — agrega el token a Secrets
  • Conflicto entre versiones de paquetes — fija versiones específicas
  • Tiempo de espera de red agotado — comprueba si se necesita VPN
  • URL del registro mal configurada
Solución: Agrega la autenticación del registro en tu sección maintenance. Consulta Ejemplos de configuración para ver patrones de registros privados.

​
Fallos por tiempo de espera

Síntoma: La compilación parece atascada y luego falla. Causas comunes:
  • Un prompt interactivo está esperando entrada — agrega flags -y, usa DEBIAN_FRONTEND=noninteractive
  • La instalación de un gran volumen de dependencias tarda demasiado
  • El comando supera el tiempo de espera de 1 hora
Solución: Agrega flags no interactivos a todos los comandos de instalación. Mueve las instalaciones únicas lentas a initialize para que solo se ejecuten durante las compilaciones (no en cada sesión). 
# Incorrecto — se quedará esperando una entrada
initialize: |
  sudo apt-get install libpq-dev

# Correcto — no interactivo
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
Errores de permisos

Síntoma: “Permiso denegado” en los registros. Causas comunes:
  • Falta sudo para instalar paquetes del sistema
  • Intento de escribir en directorios protegidos
  • Archivo propiedad de un usuario distinto de una compilación anterior
Solución: Usa sudo para operaciones a nivel del sistema (apt-get, escribir en /etc/, etc.). Para gestores de paquetes a nivel de usuario (npm, pip, cargo), normalmente no se necesita sudo.

​
Errores de “comando no encontrado”

Síntoma: Una herramienta instalada en initialize no está disponible en maintenance ni en pasos posteriores. Causas comunes:
  • La herramienta se instala en un directorio que no está en PATH
  • Los cambios en el perfil del shell (.bashrc) no se aplican en los pasos posteriores
Solución: Agrega el directorio de la herramienta a PATH mediante $ENVRC: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
Paso 4: Iterar

Después de identificar el problema:
  1. Corrige tu configuración YAML
  2. Guarda — una nueva compilación se activa automáticamente
  3. Revisa los registros de la nueva compilación
Prueba primero los comandos. Antes de agregar un comando a tu configuración, intenta ejecutarlo en una sesión de Devin para asegurarte de que funcione. Esto es más rápido que esperar a que termine un ciclo de compilación completo.

​
Referencia rápida de errores comunes

ErrorCausa probableSolución
command not foundLa herramienta no está instalada o no está en PATHAgrégala a initialize o añádela a PATH mediante $ENVRC
Permission deniedFalta sudoUsa sudo apt-get install para paquetes del sistema
npm ERR! 404Paquete privado, sin autenticaciónAgrega el token de autenticación del registry en maintenance (examples)
E: Unable to locate packageNo se ejecutó apt-get update antesAgrega sudo apt-get update -qq antes de apt-get install
TimeoutInstalación lenta o prompt interactivoMuévelo a initialize; agrega -y y DEBIAN_FRONTEND=noninteractive
Archivos de configuración vacíos después del inicio de la sesiónLas credenciales se escribieron en initializeMueve los pasos de credenciales a maintenance
La compilación se completa correctamente, pero la sesión queda inutilizableEl comando maintenance falla al inicio de la sesiónPrueba manualmente los comandos de maintenance en una sesión

​
Migrar desde la configuración interactiva

Si actualmente usas la configuración interactiva heredada (el asistente paso a paso), puedes migrar a la configuración declarativa para mejorar la reproducibilidad y la compatibilidad con múltiples repositorios.

​
Cómo funciona la migración

La configuración heredada y la configuración declarativa generan cada una su propia imagen de la máquina. Las sesiones usan una u otra, nunca una combinación híbrida. Un interruptor a nivel de la org llamado “Usar instantánea heredada de la máquina” controla qué imagen se usa:
  • Interruptor ACTIVADO (predeterminado) — todas las sesiones usan la instantánea heredada. Sin interrupciones.
  • Interruptor DESACTIVADO — todas las sesiones usan la instantánea declarativa.
Esto significa que puedes configurar y probar la configuración declarativa en paralelo mientras todos los demás siguen trabajando con la instantánea heredada.

​
Pasos de migración

1

Prepara tu configuración

Anota los comandos de tu configuración interactiva actual; luego los asignarás a secciones de YAML:
Paso del asistente heredadoEquivalente declarativo
Git pullAutomático (integrado)
Configurar SecretsSecrets (sin cambios)
Instalar dependenciasSección initialize
Mantener dependenciasSección maintenance
Configurar lintEntrada de knowledge con el nombre lint
Configurar pruebasEntrada de knowledge con el nombre test
Ejecutar la app localmenteEntrada de knowledge con el nombre startup
Notas adicionalesEntrada de knowledge con el nombre notes
2

Escribe tu YAML

Ve a Settings > Devin’s Environment y selecciona tu repositorio. Asigna tus comandos heredados:
# Legacy "Install Dependencies" → initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# Legacy "Maintain Dependencies" → maintenance
maintenance: |
  pnpm install

# Legacy "Set up lint/tests/app/notes" → knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Always run lint before committing.
O simplemente inicia una sesión de Devin y pídele que configure el repositorio; Devin puede generar la configuración automáticamente por ti.
3

Guarda y espera la compilación

Guarda tu configuración. Se iniciará una compilación automáticamente. Supervisa el progreso en Build History. Las compilaciones son gratuitas: no consumen ACUs.
4

Prueba antes de cambiar

Antes de migrar a todos, prueba la configuración declarativa en sesiones individuales con la anulación manual. Esto te permite a ti (o a quien esté iterando en la configuración) usar la instantánea declarativa mientras todos los demás siguen en la instantánea heredada.Sigue iterando en la configuración hasta que la configuración declarativa alcance plena paridad con tu Environment heredado.
5

Haz el cambio

Cuando estés seguro, cambia a OFF la opción “Use legacy machine snapshot” en la configuración de tu org. Todas las sesiones nuevas usarán ahora la instantánea declarativa.
Los flujos de autenticación interactivos (por ejemplo, el inicio de sesión en el navegador con AWS SSO o los flujos de OAuth que requieren un navegador) no pueden replicarse en el formato declarativo. Si tu configuración heredada usa autenticación basada en navegador, tendrás que convertir esos flujos a alternativas sin interfaz gráfica (API keys, tokens de cuenta de servicio, etc.) antes de migrar. Agrega credenciales a Secrets y haz referencia a ellas en tu sección maintenance.

​
Migración para Enterprise

Para empresas con múltiples organizaciones:
  1. Configura primero el YAML a nivel Enterprise — infraestructura compartida, como VPN, certificados y configuración del proxy.
  2. Migra un org a la vez. Cada org tiene su propia opción heredada, por lo que puedes migrar de forma progresiva sin afectar a otros equipos.
  3. Considera un org de prueba. Para empresas grandes, crea una organización de prueba dedicada para validar la configuración declarativa antes de implementarla en los orgs de producción.
  4. Usa Devin para escalar. Devin puede configurar repositorios mediante sesiones en paralelo: inicia una sesión por repositorio y Devin generará automáticamente propuestas de configuración. Esto funciona bien para incorporar entre 10 y más de 100 repositorios.

​
¿Qué pasa con mi instantánea anterior?

Tu instantánea anterior se conserva. Si la nueva compilación declarativa falla, Devin vuelve a la instantánea más reciente que se haya generado correctamente (que puede ser la heredada). También puedes restaurar instantáneas anteriores desde el Build History.

​
Diferencias clave

CaracterísticaHeredado (interactivo)Declarativo (YAML)
ReproducibilidadCon estado: las instantáneas acumulan cambios con el tiempoTotalmente reproducible a partir de YAML
Multi-repoUn repositorio a la vezMúltiples repositorios en una compilación con clonación simultánea
MantenimientoPasos manuales para «mantener las dependencias»Automático — maintenance se ejecuta al inicio de la sesión
Capas de Enterprise/orgNo compatibleJerarquía de 3 niveles (Enterprise → Org → Repositorio)
Sugerencias de DevinSolo en el asistenteDurante la sesión — Devin puede sugerir actualizaciones de configuración
CostoLas sesiones del asistente consumían ACULas sesiones de configuración consumen ~1–3 ACU; las compilaciones son gratuitas

​
Preguntas frecuentes

​
General

¿Qué pasa si ejecuto una sesión en un repositorio que no está configurado? Devin seguirá funcionando; simplemente tendrá que averiguar tu proyecto desde cero cada vez. Eso implica dedicar tiempo a instalar dependencias, descubrir cómo compilar y probar, y deducir las convenciones. Las sesiones tardan más y consumen más ACUs. Configurar tu entorno hace que Devin inicie cada sesión ya preconfigurado y listo para usar. ¿Cuánto tarda una compilación? Normalmente, entre 5 y 15 minutos, según la cantidad de repositorios y el tamaño de las dependencias. Las compilaciones expiran tras 2 horas. ¿Cuánto cuesta esto? Las compilaciones son gratuitas; no consumen ACUs. Si usas una sesión de Devin para configurar un repositorio (por ejemplo, pidiéndole a Devin que genere tu configuración), esa sesión suele costar entre 1 y 3 ACUs. Una vez guardada la configuración, todas las compilaciones posteriores a partir de ella son gratuitas. ¿Puedo usar tanto la configuración heredada como la declarativa? Una organización usa un solo modo a la vez, controlado por el interruptor “Use legacy machine snapshot”. Puedes configurar la configuración declarativa en paralelo mientras el interruptor siga activado (modo heredado) y luego cambiar cuando estés listo. Consulta la guía de migración para obtener más detalles. ¿Puedo probar la configuración declarativa sin afectar a otros usuarios? Sí. Usa la anulación manual en sesiones individuales para usar temporalmente la instantánea declarativa mientras los demás siguen con la instantánea heredada. En Enterprise, también puedes crear una organización de prueba dedicada. ¿Qué pasa si falla mi compilación? Devin usa la instantánea correcta más reciente. Una compilación fallida no interrumpe las sesiones existentes. ¿Cuándo debo usar initialize en lugar de maintenance? Usa initialize para instalaciones únicas de herramientas (apt-get install, configuración del entorno de ejecución del lenguaje, herramientas CLI globales). Usa maintenance para la instalación de dependencias que deben mantenerse actualizadas (npm install, pip install, uv sync). ¿Cómo agrego variables de entorno? Escríbelas en $ENVRC: 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
¿Puedo instalar paquetes del sistema? Sí, usa sudo apt-get install en tu sección initialize. Usa siempre DEBIAN_FRONTEND=noninteractive y la opción -y para evitar prompts interactivos. ¿Qué pasa si necesito versiones distintas de Node para diferentes repositorios? Usa nvm en la configuración de tu repositorio: 
initialize: |
  nvm install 18
  nvm use 18
¿Se admiten flujos de autenticación interactivos? No. La autenticación basada en el navegador (como el inicio de sesión con AWS SSO o los flujos de OAuth que requieren una ventana del navegador) no puede reproducirse en el formato declarativo. Convierte estos flujos en alternativas sin interfaz gráfica: usa API keys, tokens de cuentas de servicio u otros métodos basados en credenciales, y almacénalos en Secrets. Actualmente no existe ninguna solución alternativa para los workflows que requieren estrictamente SSO basado en navegador. Estos repositorios deben seguir usando la configuración interactiva hasta que haya alternativas sin interfaz gráfica disponibles.

​
Sobre la compilación

¿Qué significa “éxito parcial”? La compilación principal (Enterprise + configuración del org + clonación) se completó correctamente, pero una o más configuraciones a nivel de repositorio fallaron. Las sesiones funcionarán, pero es posible que los repositorios que fallaron no tengan sus dependencias instaladas correctamente. ¿Por qué se canceló mi compilación? Se activó una compilación más reciente antes de que terminara tu compilación. Solo se ejecuta la compilación más reciente; las compilaciones anteriores en cola se cancelan automáticamente. ¿Cambiar la configuración de un repositorio vuelve a compilarlo todo? Sí: una compilación crea una única imagen de la máquina que contiene todos los repositorios configurados. Cualquier cambio en la configuración activa una recompilación completa. ¿Puedo volver a una compilación anterior? Sí, desde Build History en Environment Settings. Puedes restaurar cualquier instantánea anterior que se haya completado correctamente. ¿Cuántos repositorios puedo incluir? Durante una compilación, se clonan hasta 10 repositorios de forma concurrente. No hay un límite estricto para el total de repositorios, pero cuantos más repositorios haya, más tardarán las compilaciones. Devin puede configurar repositorios a gran escala mediante sesiones en paralelo: inicia una sesión por repositorio para 10–100+ repositorios.

​
Específico de Enterprise

¿Quién puede editar la configuración a nivel de Enterprise? Solo los administradores de Enterprise. Los administradores de org pueden editar la configuración de toda la org y la configuración a nivel de repositorio. Los miembros habituales pueden editar la configuración a nivel de repositorio si tienen el permiso ManageOrgSnapshots. Consulta Configuración de Environment de Enterprise para ver la tabla completa de permisos. ¿Cambiar la configuración de Enterprise vuelve a compilar todas las orgs? Sí. Un cambio a nivel de Enterprise desencadena compilaciones para cada organización dentro de Enterprise. ¿Pueden distintas orgs tener configuraciones diferentes? Sí. Cada org tiene su propia configuración de toda la org y sus propias configuraciones a nivel de repositorio. La configuración de Enterprise es compartida y aditiva; se ejecuta antes que la configuración de cada org. ¿Pueden las configuraciones de niveles inferiores sobrescribir las de niveles superiores? No. La jerarquía (Enterprise → Org → Repositorio) es estrictamente aditiva. Los comandos de cada nivel se ejecutan en secuencia después de que termina el nivel anterior. Los niveles inferiores no pueden impedir ni modificar lo que configuran los niveles superiores. ¿Puede la configuración a nivel de Enterprise clonar repositorios? No. La clonación de repositorios requiere acceso a nivel de org. La configuración a nivel de Enterprise puede instalar herramientas e infraestructura compartidas, pero la clonación de repositorios debe configurarse a nivel de org o de repositorio.

​
Limitaciones conocidas

  • Sin vista previa ni entorno aislado de compilación — cada cambio de configuración activa una compilación completa. Prueba primero los comandos en una sesión.
  • Configuración secuencial del repositorio — la configuración a nivel de repositorio se ejecuta un repositorio a la vez (en orden alfabético). Un gran número de repositorios implica compilaciones más largas.
  • Sin lógica condicional en YAML — el formato no admite if/else. Usa condicionales de shell en tus comandos si es necesario (p. ej., [ -f package.json ] && npm install).
  • Sin búsqueda en los registros de compilación — los registros de compilación deben recorrerse manualmente. Usa pasos con nombre para que los fallos sean más fáciles de encontrar.

​
Próximos pasos