Saltar al contenido principal
Implementar Devin en una empresa implica gestionar entornos para decenas de organizaciones y cientos de repositorios. En esta página se describen los patrones que mejor funcionan a escala y los errores que conviene evitar.

​
Organizar blueprints por nivel

La pregunta más común que hacen los administradores de Enterprise es: “¿Dónde debe ir esta configuración?” La respuesta es simple: ponla en el blueprint de Enterprise de forma predeterminada. El blueprint de Enterprise es el lugar adecuado para todo lo que se aplique (o pueda aplicarse) a todas las organizaciones. Esto incluye entornos de ejecución, herramientas de seguridad, certificados corporativos, CLIs internos, configuración de proxy y autenticación compartida para registros. Está perfectamente bien instalar múltiples lenguajes y herramientas aquí, aunque no todas las org los usen todos.
Nivel de blueprintCuándo usarloEjemplos
EnterprisePredeterminado para toda la configuración compartidaPython 3.12, Node 20, Go 1.22, Rust, escáneres de seguridad, certificados de AC corporativa, CLIs internos, configuración de proxy, tokens compartidos para registros
OrganizationSolo cuando algo no deba aplicarse a todas las orgUn registro privado específico de un equipo, herramientas restringidas a ciertos equipos, configuración de linting específica de la org
RepositoryConfiguración por repo que se ejecuta en el directorio del reponpm install, uv sync, elementos de Knowledge específicos del proyecto, archivos .envrc a nivel de repo
La única razón para usar un blueprint de org en lugar del blueprint de Enterprise es cuando expresamente no quieres que algo se aplique a todas las organizaciones. Por ejemplo, si un equipo usa un registro privado de npm al que otros equipos no deberían tener acceso, esa configuración del registro debe ir en el blueprint de org de ese equipo, no en el blueprint de Enterprise. Si algo se aplica a todas las orgs, va en Enterprise. Si es específico del repo, va en el blueprint del repo. El nivel de org existe solo para las excepciones intermedias.
No pongas comandos específicos del repo (como npm install) en el blueprint de Enterprise ni en el de org. Esos niveles se ejecutan en el directorio de inicio, no en el directorio del repo, por lo que los comandos específicos del repo fallarán o se instalarán en el lugar equivocado.

​
Usa los elementos de Knowledge en el nivel correcto

Los elementos de Knowledge se acumulan entre niveles. Devin los ve todos. Úsalo para organizar la orientación por capas:
  • Knowledge de Enterprise: Estándares de codificación de toda la empresa, requisitos de revisión de seguridad y enlaces a documentación interna.
  • Knowledge de la org: Convenciones del equipo, patrones de uso de bibliotecas compartidas y procedimientos de despliegue específicos del equipo.
  • Knowledge del repo: Comandos de lint, pruebas y compilación para el proyecto específico.

​
Gestión de secretos a escala

Los secretos siguen la misma jerarquía de niveles que los blueprints, y los secretos más específicos tienen prioridad.

​
Dónde definir los secretos

Ámbito del secretoSe usa paraEjemplos
EnterpriseCredenciales compartidas entre todas las organizacionesTokens del registro interno, autenticación en el proxy corporativo, claves de API compartidas para servicios internos
OrganizaciónCredenciales específicas del equipoClaves de despliegue del equipo, tokens de API para servicios del equipo, autenticación en el registro del equipo
RepositorioCredenciales específicas del repositorioClaves de API por proyecto, cuentas de servicio específicas del proyecto
Coloca los secretos en el nivel más alto que corresponda. Si todas las organizaciones necesitan acceso al registro interno de npm, define el token una sola vez como un secreto de Enterprise. No lo dupliques en la configuración de 50 organizaciones.

​
Gestión segura de secretos

  • Nunca incluyas secretos en YAML. Usa siempre la interfaz de gestión de secretos. Los secretos en YAML acaban en los registros, los artefactos de compilación y los registros de auditoría.
  • Rota los secretos con regularidad. Cuando rotas un secreto en la interfaz, el nuevo valor entra en vigor en la siguiente compilación. No hace falta cambiar el blueprint.
  • Usa nombres descriptivos. INTERNAL_NPM_TOKEN es mejor que TOKEN_1. Otros administradores (y tu yo del futuro) necesitan comprender para qué sirve cada secreto.
  • Audita el uso de los secretos. Revisa periódicamente qué secretos existen y si siguen siendo necesarios. Elimina los secretos que no se usen para reducir la superficie de ataque.
Si un secreto de la organización y un secreto de Enterprise tienen el mismo nombre, prevalece el secreto de la organización. Lo mismo ocurre cuando los secretos del repositorio reemplazan a los de la organización. Usa este comportamiento de forma intencional. Por ejemplo, una organización podría reemplazar el token del registro de Enterprise por un token específico del equipo con permisos diferentes.

​
Supervisión del estado de las compilaciones

A escala empresarial, los fallos de compilación son inevitables. La clave está en detectarlos pronto y resolverlos con rapidez.

​
Establece una frecuencia de revisión

Revisa semanalmente el estado de las compilaciones en todas las organizaciones. Busca lo siguiente:
  • Compilaciones fallidas: Fallos críticos en los blueprints de Enterprise o de las orgs que bloquean todos los repos.
  • Compilaciones parciales: Algunos repos fallan. Suele ser señal de un problema de dependencias o de un blueprint desactualizado.
  • Compilaciones desactualizadas: Orgs cuya compilación más reciente es inusualmente antigua, lo que puede indicar que la cola de compilación está atascada.

​
Responde a los fallos del blueprint de Enterprise

Si un cambio en el blueprint de Enterprise provoca fallos generalizados:
  1. Evalúa el alcance del impacto. Comprueba cuántas organizaciones se ven afectadas en la página Rollout.
  2. Revierte el blueprint de Enterprise al último blueprint que se sabe que funciona correctamente. Guarda de inmediato. Esto activa recompilaciones en todas las organizaciones afectadas.
  3. Investiga de forma aislada. Prueba tus cambios en una sola organización piloto antes de volver a implementarlos.
No dejes un blueprint de Enterprise roto mientras depuras. Cada minuto que sigue roto, las organizaciones reciben compilaciones fallidas.

​
Las compilaciones parciales son una señal

Una compilación parcial significa que algunos repositorios de una org se completaron correctamente mientras que otros fallaron. Esto suele deberse a lo siguiente:
  • Un problema de dependencias específico de un repositorio (archivo de bloqueo dañado, paquete eliminado)
  • Falta una biblioteca del sistema que solo necesita un proyecto
  • Un blueprint desactualizado que no se ha ajustado a los cambios del repositorio
Las compilaciones parciales siguen generando instantáneas utilizables para los repositorios que se completaron correctamente. Pero investiga los fallos. Tienden a acumularse si se ignoran.

​
Cuándo fijar compilaciones

Fijar compilaciones congela el entorno de una organización en una instantánea específica. Hazlo deliberadamente.

​
Buenas razones para fijar compilaciones

  • Lanzamiento crítico en curso. Necesitas un entorno estable y validado durante las próximas 48 horas mientras lanzas una versión.
  • Depuración activa. Estás investigando un problema de compilación y no quieres que las actualizaciones automáticas cambien nada en pleno proceso.
  • Reversión. Una nueva compilación introdujo una regresión y necesitas revertirla de inmediato mientras corriges el blueprint.

​
Malas razones para fijar

  • Evitar una solución. Si una compilación está rota, corrige el blueprint. Fijarla oculta el problema y, como las fijaciones no caducan automáticamente, una fijación olvidada puede hacer que sigas ejecutando un entorno obsoleto indefinidamente.
  • “Por si acaso.” Las actualizaciones automáticas mantienen las dependencias al día y detectan los problemas pronto. Desactivarlas sin ningún motivo específico solo retrasa los problemas.
Solo puedes fijar compilaciones de menos de 7 días de antigüedad. Una vez fijada, la fijación sigue activa hasta que se quite manualmente. No caduca. Una fijación olvidada significa que tu equipo está ejecutando una instantánea cada vez más obsoleta.

​
Migrar tu empresa

Para consultar el playbook recomendado para una migración por fases (desde las pruebas iniciales hasta el despliegue completo), consulta Migrar tu empresa.

​
Patrones de arquitectura comunes

Las distintas estructuras empresariales requieren diferentes enfoques de blueprint.

​
Organizaciones monorepo

Configuración: Una org con un único repositorio grande que contiene múltiples proyectos. Enfoque: La blueprint Enterprise se encarga de todas las herramientas compartidas (runtimes, herramientas CLI globales, registries). Coloca la configuración específica de cada proyecto (npm install en el directorio del frontend, uv sync en el directorio del backend) en la blueprint del repositorio. La blueprint de la org solo es necesaria si esta org tiene herramientas o configuración que no deberían aplicarse a otras orgs. 
# Repo blueprint para un monorepo
maintenance:
  - name: "Frontend dependencies"
    run: (cd frontend && npm install)

  - name: "Backend dependencies"
    run: (cd backend && uv sync)

knowledge:
  - name: lint
    contents: |
      Frontend: cd frontend && npm run lint
      Backend: cd backend && uv run ruff check .

​
Organizaciones con varios repositorios

Configuración: Una org con varios repositorios relacionados (p. ej., un equipo de microservicios). Enfoque: Coloca las herramientas compartidas y la configuración del registro en el blueprint de la org. Cada repo tiene su propio blueprint con solo maintenance y Knowledge. Esto evita duplicar comandos de configuración entre repositorios.

​
Org de infraestructura compartida

Configuración: Un org de plataforma o de DevOps que proporciona servicios compartidos que usan otros equipos. Enfoque: El blueprint de Enterprise cubre la base común. El blueprint del org de infraestructura compartida instala las herramientas específicas de la plataforma (Terraform, kubectl y CLI de nube) que necesitan sus repos. Los demás orgs no reciben estas herramientas. Solo obtienen lo que incluye el blueprint de Enterprise, además de la configuración de su propio org.

​
Organizaciones de proyecto aisladas

Configuración: Equipos independientes sin herramientas compartidas más allá de lo básico. Enfoque: El blueprint Enterprise sigue encargándose de la base común: todos tus entornos de ejecución estándar, herramientas de seguridad y la infraestructura corporativa. Cada organización usa su propio blueprint solo para herramientas o configuraciones que sean realmente exclusivas de ese equipo y no deban compartirse con otros. Los blueprints del repositorio se encargan de la configuración de cada proyecto.
En caso de duda, inclúyelo en el blueprint Enterprise. Si una organización tiene un motivo específico para excluir algo (versiones de herramientas en conflicto, acceso restringido), puede anularlo a nivel de la organización. Es más fácil contar con una base de referencia Enterprise completa que duplicar la configuración en muchos blueprints de organización.