Blueprints de Environment de Devin

Primeros pasos

Requisitos previos: Devin debe tener acceso a tus repositorios antes de que puedas configurar su entorno. Si todavía no configuraste la integración con Git, consulta Antes de empezar para ver los pasos de configuración. Los usuarios de Enterprise también deben otorgar a cada organización acceso a sus repositorios en Enterprise Settings > Repository Permissions.

Un blueprint es el formato que Devin utiliza para describir un entorno: las herramientas que se deben instalar, las dependencias que se deben mantener y los comandos que debe conocer. Devin puede generar un blueprint a partir de tu repositorio, y puedes revisarlo o editarlo cuando quieras tener más control sobre la configuración.

Deja que Devin lo haga (recomendado)
Configuración manual

Lo mejor para la mayoría de los usuarios. Devin inspecciona tu repositorio, identifica qué herramientas, entorno de ejecución y dependencias hacen falta y genera el blueprint por ti. Revisas y apruebas la configuración sugerida antes de que se compile.

Inicia una sesión de Devin

Abre una nueva sesión y pídele a Devin que configure el repositorio. Por ejemplo: “Configura tu entorno para este repositorio.”

Revisa y aprueba

Devin propone un blueprint según lo que encontró. Verás tarjetas de sugerencias en tu línea de tiempo. Revisa las herramientas, dependencias y comandos propuestos, y luego haz clic en Approve.

Compila y verifica

Una vez que apruebes las sugerencias, se ejecuta una compilación y se genera una instantánea. Inicia una nueva sesión para arrancar desde ella y luego pídele a Devin que ejecute tus comandos de lint o de prueba para confirmar que todo funciona.

Consulta el video y resumen de la configuración con un solo prompt en el centro de Environment.

Lo mejor cuando sabes exactamente qué necesita tu entorno o quieres control total sobre cada paso. Es más rápido si ya tienes los comandos listos.

Ve a la Configuración de Environment

Ve a Settings > Environment > Blueprints en la barra lateral de tu organización.Si no ves esta opción, contacta con el administrador de tu empresa para confirmar que los blueprints de entorno estén habilitados para tu organización.

Agrega repositorios

Haz clic en Add en la sección Repositories. Selecciona los repositorios con los que quieres que trabaje Devin y luego confirma.Los repositorios que agregues aquí se clonan en el Environment de Devin durante cada compilación. Puedes agregar más en cualquier momento.

Escribe tu blueprint

Haz clic en un repositorio para abrir su editor de blueprint. Aquí tienes un ejemplo sencillo:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest

Para ver más lenguajes y patrones, consulta la biblioteca de plantillas.

Guarda y compila

Haz clic en Save. Se inicia una compilación automáticamente. El tiempo de compilación depende de cuántos repositorios hayas configurado y de cuánto trabajo realicen tus blueprints, así que sigue el progreso en Settings > Environment > Snapshots, en Compilación actual.

Verifica

Cuando la compilación muestre éxito, inicia una nueva sesión de Devin. Devin arranca desde la nueva instantánea con todo preconfigurado. Prueba a pedirle a Devin que ejecute tus comandos de lint o de prueba para verificar que el entorno funciona.

El resto de esta guía explica cómo funciona el blueprint generado y cómo editarlo cuando quieras tener más control.

Verlo aplicado de principio a fin

Escenarios: crecer con ACME Corp — un repositorio, luego múltiples repositorios con dependencias compartidas y después múltiples organizaciones. Blueprints completos para cada etapa y cómo decidir a qué nivel pertenece cada cosa.

Cómo funciona

La configuración declarativa utiliza tres conceptos:

Concepto	Qué es	Analogía
Blueprint	Una configuración YAML que describe qué instalar y cómo configurar el Environment de Devin	Dockerfile
Compilación	El proceso que ejecuta tu blueprint, clona repositorios y produce una instantánea	`docker build`
Instantánea	Una imagen congelada y arrancable del entorno a partir de la cual se inician las sesiones	Imagen de Docker

Los blueprints describen lo que quieres. Los creas y editas en la interfaz de usuario de Settings. Las compilaciones ejecutan tus blueprints para generar instantáneas. Las compilaciones se ejecutan automáticamente cuando guardas un blueprint y de forma periódica (~cada 24 horas) para mantener las dependencias actualizadas. Las instantáneas son la base desde la que se inician las sesiones. Cada organización tiene una instantánea activa. Cada sesión se inicia desde una copia limpia. Los cambios de la sesión no se conservan en la instantánea.

Secciones del blueprint

Un blueprint tiene tres secciones principales, además de un bloqueo post-build para blueprints de organización/Enterprise y un bloqueo clone opcional para blueprints de nivel de repositorio:

Section	Purpose	When it runs
`initialize`	Instala herramientas, entornos de ejecución y paquetes del sistema	Solo durante las compilaciones. Los resultados se guardan en la instantánea.
`maintenance`	Instala o actualiza las dependencias del proyecto y escribe configuraciones de credenciales	Durante las compilaciones. Se muestra al agente al inicio de la sesión (no se ejecuta automáticamente).
`knowledge`	Información de referencia para Devin (comandos de lint, test y compilación)	No se ejecuta. Se carga en el contexto de Devin al inicio de la sesión.
`post-build`	Valida el entorno completamente ensamblado (solo para organización/Enterprise)	Durante las compilaciones, después de que todos los repositorios se hayan clonado y configurado. Una salida distinta de cero hace fallar la compilación.
`clone`	Anula los valores predeterminados de git-clone para el repositorio (solo para blueprints de nivel de repositorio)	Se aplica durante el paso de clonación de la compilación.

initialize es para tareas que solo deben realizarse una vez: entornos de ejecución, paquetes del sistema y herramientas CLI globales. maintenance es para la instalación de dependencias que deben mantenerse actualizadas. Se ejecuta durante las compilaciones y se muestra al agente al inicio de la sesión para que pueda volver a ejecutarlas si las dependencias han cambiado (p. ej., después de extraer el código más reciente). Los comandos no se ejecutan automáticamente al inicio de la sesión, pero aun así deben ser rápidos e incrementales (usa npm install, no npm ci). knowledge es información de referencia; no se ejecuta. Así es como le indicas a Devin los comandos correctos para linting, testing y compilación. Mantén las entradas ligeras y centradas en comandos ejecutables. post-build (solo para nivel de organización y Enterprise) se ejecuta después de que todos los repositorios se hayan clonado y configurado, justo antes de que se guarde la instantánea. Úsalo para verificar el entorno ensamblado; p. ej., comprobar que las herramientas necesarias estén instaladas o que una prueba de humo entre repositorios se complete correctamente. Un código de salida distinto de cero hace fallar la compilación, por lo que no se entrega ninguna instantánea sin superar tus comprobaciones. Consulta referencia de Blueprint → post-build. clone (solo para blueprints de nivel de repositorio) anula los valores predeterminados que Devin usa al clonar el repositorio en la instantánea; por ejemplo, para cambiar a una rama no predeterminada (ref), cambiar el destino de clonación (path) u omitir submódulos u objetos LFS. Todos los campos son opcionales. Consulta referencia de Blueprint → clone para ver la lista completa de campos.

Knowledge aquí frente a la función de producto Knowledge: La sección knowledge de tu blueprint es para referencias breves de comandos vinculadas al entorno. Para documentación de arquitectura, convenciones y flujos de trabajo del equipo, usa en su lugar la función independiente Skills.

YAML de varios documentos: El editor de blueprint admite YAML de varios documentos mediante el separador ---. Esto te permite organizar blueprints complejos en secciones lógicas dentro de un único editor.

Para ver la especificación completa de los campos (tipos de pasos, variables de entorno, secretos y archivos adjuntos), consulta la referencia de Blueprint.

Ámbito del blueprint

Puedes definir blueprints en dos niveles:

Nivel	Dónde configurarlo	Qué incluir aquí
Organización	Settings > Environment > Blueprints > Organization blueprint	Herramientas compartidas en todos los repositorios: entornos de ejecución, gestores de paquetes, autenticación de Docker
Repositorio	Settings > Environment > Blueprints > [nombre del repo]	Configuración específica del proyecto: `npm install`, comandos de lint/test/build

Los blueprints son acumulativos: los blueprints de los repositorios se añaden sobre el blueprint de la organización. El maintenance de un repositorio puede usar herramientas instaladas por el initialize de la organización. Si solo un repositorio necesita una herramienta, colócala en el blueprint de ese repositorio. Si todos los repositorios la necesitan, colócala en el blueprint de la organización. Para monorepos, un repositorio puede tener un blueprint raíz y blueprints de workspace por subdirectorio, cada uno con sus propias secciones initialize, maintenance y knowledge, además de su directorio de trabajo. Consulta Workspaces y monorepos para ver instrucciones de configuración y ejemplos. Para ver ejemplos prácticos de cómo elegir un nivel a medida que crece una base de código, consulta Escenarios: crecer con ACME Corp.

Usuarios de Enterprise: Hay un tercer nivel, el blueprint de Enterprise, que se aplica a todas las organizaciones. Consulta la descripción general del entorno de Enterprise para obtener más información.

Compilaciones y sesiones

La instantánea

Tu organización tiene una instantánea activa: una imagen de máquina virtual con tus herramientas, repositorios y dependencias preinstalados. Todos los repositorios configurados se clonan y se preparan en esa única imagen. Cada sesión se inicia a partir de una copia limpia.

Cómo funcionan las compilaciones

Una compilación crea una nueva instantánea al ejecutar tus blueprints en secuencia:

1. Blueprint de enterprise, si está configurado (se ejecuta en ~):
   a. initialize
   b. maintenance
2. Blueprint de organización (se ejecuta en ~):
   a. initialize
   b. maintenance
3. Clonado de todos los repositorios (hasta 10 simultáneos).
   El blueprint de cada repositorio puede anular los valores predeterminados
   de clonado mediante el block `clone` (rama/etiqueta, profundidad, submódulos, LFS, etc.).
4. Para cada repositorio configurado, en el orden que aparece en Settings
   (se ejecuta en ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Pasos post-build (primero los del blueprint de organización y luego los del de enterprise; se ejecutan en ~)
6. comprobación de estado y, después, se guarda la instantánea

Las capas son acumulativas: los comandos específicos de un repositorio pueden usar las herramientas instaladas por el blueprint de la organización o de Enterprise. Los niveles inferiores no pueden anular lo configurado por un nivel superior. El tiempo de compilación aumenta según la cantidad de repositorios configurados y el trabajo que realizan tus blueprints. Cada paso tiene un tiempo de espera máximo de 3 horas.

Cómo funcionan las sesiones

Cada sesión arranca con una copia limpia de la instantánea. Cuando la sesión termina, se descartan todos los cambios. Al inicio de la sesión:

Se descarga el código más reciente de los repositorios relevantes.
Los comandos de maintenance (Enterprise, organización y repositorio) se presentan al agente como contexto; no se ejecutan automáticamente. El agente puede volver a ejecutarlos si detecta que las dependencias han cambiado desde la última compilación.
Las entradas de knowledge de ese repositorio se cargan en el contexto de Devin.

Knowledge es específico de cada repositorio. Si tienes 5 repositorios configurados, Devin solo ve las entradas de Knowledge del repositorio en el que está trabajando.

Qué activa una compilación

Evento	Descripción
Guardar un blueprint	Crear, actualizar o eliminar un blueprint
Agregar o quitar un repositorio	Cualquier cambio en la lista de repositorios
Agregar un secreto de repositorio	Los secretos nuevos requieren una nueva compilación para estar disponibles
Activación manual	Hacer clic en Build snapshot en la UI
Actualización periódica	Automática, aproximadamente cada 24 horas
Sugerencia de Devin	Devin propone un cambio en el blueprint durante una sesión

Solo se ejecuta una compilación a la vez. Los eventos nuevos cancelan cualquier compilación en cola y la reinician desde cero.

Estados de compilación

Estado	Significado
En cola	La compilación se aceptó y está a la espera de una máquina.
En compilación	Los pasos de configuración se están ejecutando en la máquina de compilación.
Éxito	Se completaron todos los pasos. La instantánea está lista.
Parcial	Algunos pasos a nivel de repositorio fallaron, pero la instantánea se puede usar. Los repositorios que se configuraron correctamente funcionan con normalidad; es necesario corregir los blueprints de los repositorios que fallaron.
Fallido	La instantánea no se puede usar. Esto ocurre cuando falla un blueprint de organización o de Enterprise (incluidos sus pasos post-build), no se puede clonar un repositorio o la máquina no supera las comprobaciones de estado finales.
Cancelado	Se sustituyó por una compilación más reciente o se canceló manualmente.

Una compilación parcial sigue generando una instantánea funcional. Se clonaron todos los repositorios, por lo que todo tu código fuente está disponible en la sesión; solo no se ejecutaron los pasos de configuración de los blueprints que fallaron. Si uno de cinco repositorios tiene un blueprint defectuoso, los otros cuatro están completamente configurados y Devin aún puede leer y trabajar en el quinto.

¿La compilación falla? Consulta Solución de problemas de compilaciones para ver una guía de depuración paso a paso.

Administrar tu Environment

Estados de los repositorios

Los repositorios aparecen en tres estados en los Settings de Environment:

Estado	Significado
Configurado	Tiene un blueprint con initialize/maintenance/knowledge. Está completamente configurado en la instantánea.
Incluido	Está clonado en la instantánea, pero no tiene un blueprint personalizado. Devin puede acceder al código.
Disponible	Está conectado a la organización, pero no se agregó al entorno. No está clonado.

Incluido vs. configurado: Un repositorio “incluido” está clonado para que Devin pueda acceder al código, pero no tiene comandos de configuración personalizados. Un repositorio “configurado” tiene instrucciones explícitas de initialize/maintenance/knowledge.

Secretos

Usa la sintaxis $VARIABLE_NAME para hacer referencia a los secretos. Agrégalos en la pestaña Secretos dentro del editor de blueprint.

maintenance:
  - name: Configure private registry
    run: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

Los secretos están disponibles como variables de entorno durante las compilaciones y las sesiones. Se eliminan antes de guardar la instantánea, pero si un comando escribe un valor secreto en un archivo de configuración durante initialize, ese valor permanece en la instantánea. Coloque los pasos que escriben credenciales en maintenance para que se actualicen durante las compilaciones periódicas. Para obtener más información sobre los ámbitos de los secretos y su comportamiento, consulte la referencia de Blueprint.

Múltiples repositorios

Cada repositorio tiene su propio blueprint. Durante una compilación, todos los repositorios se configuran en la misma instantánea, se clonan en directorios separados y sus dependencias se instalan de forma independiente. Si dos repositorios instalan versiones diferentes de una herramienta global o modifican archivos compartidos (como ~/.bashrc), prevalece el último que se ejecuta. Para evitar conflictos, coloca las instalaciones de herramientas compartidas en el blueprint de toda la organización.

GitHub Actions

En lugar de escribir scripts de shell para instalar herramientas y entornos de ejecución, puedes referenciar GitHub Actions directamente en tu blueprint. Devin descarga y ejecuta la acción durante la compilación, igual que los runners de CI de GitHub ejecutan los pasos de una acción.

initialize:
  - name: Install Python 3.12
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

Esto es especialmente útil para acciones de configuración de lenguajes como setup-python, setup-node y setup-go, que gestionan automáticamente las versiones y la configuración de PATH. Para obtener detalles sobre la sintaxis, ejemplos y limitaciones, consulta GitHub Actions en blueprints.

Monorepos

Puedes ejecutar comandos en subdirectorios usando subshells, o crear blueprints específicos de cada workspace para paquetes individuales. Devin también admite entradas de Knowledge por paquete para que cada workspace tenga sus propios comandos de lint, test y compilación. Consulta Workspaces y monorepos para obtener instrucciones de configuración y ejemplos.

Anclaje y actualizaciones automáticas

De forma predeterminada, Devin usa la instantánea de la compilación exitosa más reciente. Anclar te permite fijar la instantánea de una compilación específica. Esto es útil cuando una compilación nueva introduce una regresión o cuando quieres congelar el entorno para un conjunto de sesiones. Para anclar: Ve a Settings > Environment > Snapshots, busca la compilación en el historial (debe ser success o partial y tener menos de 7 días de antigüedad), abre su menú y haz clic en Use this build. Mientras esté anclada, se omiten las actualizaciones periódicas, la compilación se marca como Locked y la interfaz muestra Auto-updates paused. Para desanclar: Haz clic en Resume auto-updates. Devin cambia a la compilación exitosa más reciente.

blueprints respaldados por Git

Puedes almacenar blueprints como archivos .devin/blueprint.yaml directamente en tu repositorio. Después de fusionar los cambios, llama a la API de sincronización (o haz clic en Sync en la UI) para actualizar el blueprint y luego iniciar una compilación. Así obtienes el mismo flujo de revisión de código que usas para el código de la aplicación, con la sincronización automatizada mediante un paso de CI. Consulta Git-backed blueprints para ver las instrucciones de configuración y más detalles.

Solución de problemas de compilación

Falló el paso `initialize`

Causas comunes: error tipográfico en un comando de shell, paquete no disponible, tiempo de espera de red agotado, referencia incorrecta de GitHub Action. Solución: Revisa los registros de compilación para ver el error exacto. Actualiza initialize en tu blueprint y guarda. Esto activa automáticamente una nueva compilación.

Falló la clonación del repositorio

Causas comunes: Devin no tiene acceso al repositorio, se cambió el nombre del repositorio/se movió/se eliminó, o hubo un problema de red transitorio. Solución: Verifica el acceso al repositorio en la configuración de tu proveedor de Git. Elimina el repositorio y vuelve a agregarlo si se cambió de nombre.

Falló el paso de mantenimiento

Causas comunes: conflicto de dependencias, falta de una biblioteca del sistema, falta de espacio en disco, archivo de bloqueo fuera de sincronización. Solución: Revisa los logs del paquete o comando que falló. Actualiza maintenance o initialize para instalar las dependencias que faltan, o corrige el archivo de bloqueo en tu repositorio.

Tiempo de espera de compilación

Cada paso del blueprint tiene un tiempo límite de 3 horas. Las clonaciones y las actualizaciones (pull) de repositorios tienen el mismo tiempo límite de 3 horas. Algunas causas comunes: compilar grandes dependencias nativas desde el código fuente (use binarios precompilados), descargar artefactos grandes y comandos que quedan bloqueados esperando entrada (todos los comandos deben ejecutarse de forma no interactiva).

Iteración de correcciones

Revisa los logs de compilación para identificar el fallo
Actualiza el blueprint correspondiente
Guarda (una nueva compilación se activa automáticamente)
Supervisa los logs de la nueva compilación
Repite hasta que la compilación finalice correctamente

No necesitas esperar a que termine una compilación fallida. Guardar una nueva configuración cancela cualquier compilación en cola y vuelve a empezar desde cero.

Siguientes pasos

Escenarios: crecer con ACME Corp

Ejemplos prácticos: un repositorio, luego múltiples repositorios con dependencias compartidas y, por último, múltiples organizaciones.

Compilaciones diferenciales

Acelera las compilaciones reconstruyendo solo los workspaces cuyos blueprints hayan cambiado.

GitHub Actions en blueprints

Usa GitHub Actions para instalar lenguajes, herramientas y SDKs sin necesidad de escribir scripts de shell.

Workspaces y monorepos

Subshells, ámbitos de workspace y entradas de Knowledge para repositorios con múltiples paquetes.

referencia de Blueprint

Referencia completa de campos: tipos de pasos, variables de entorno, secretos y archivos adjuntos.

Biblioteca de plantillas

Blueprints listos para copiar y pegar para Python, Node.js, Go, Java, Ruby, Rust y patrones avanzados.

Blueprints respaldados por Git

Guarda blueprints en tu repositorio como .devin/blueprint.yaml y sincronízalos mediante la API o la UI.

Gestión de entornos Enterprise

Gestión de entornos a nivel Enterprise: jerarquía de 3 niveles, secretos y configuración entre organizaciones.

​Primeros pasos

Verlo aplicado de principio a fin

​Cómo funciona

​Secciones del blueprint

​Ámbito del blueprint

​Compilaciones y sesiones

​La instantánea

​Cómo funcionan las compilaciones

​Cómo funcionan las sesiones

​Qué activa una compilación

​Estados de compilación

​Administrar tu Environment

​Estados de los repositorios

​Secretos

​Múltiples repositorios

​GitHub Actions

​Monorepos

​Anclaje y actualizaciones automáticas

​blueprints respaldados por Git

​Solución de problemas de compilación

​Falló el paso initialize

​Falló la clonación del repositorio

​Falló el paso de mantenimiento

​Tiempo de espera de compilación

​Iteración de correcciones

​Siguientes pasos

Escenarios: crecer con ACME Corp

Compilaciones diferenciales

GitHub Actions en blueprints

Workspaces y monorepos

referencia de Blueprint

Biblioteca de plantillas

Blueprints respaldados por Git

Gestión de entornos Enterprise

Primeros pasos

Cómo funciona

Secciones del blueprint

Ámbito del blueprint

Compilaciones y sesiones

La instantánea

Cómo funcionan las compilaciones

Cómo funcionan las sesiones

Qué activa una compilación

Estados de compilación

Administrar tu Environment

Estados de los repositorios

Secretos

Múltiples repositorios

GitHub Actions

Monorepos

Anclaje y actualizaciones automáticas

blueprints respaldados por Git

Solución de problemas de compilación

Falló el paso `initialize`

Falló la clonación del repositorio

Falló el paso de mantenimiento

Tiempo de espera de compilación

Iteración de correcciones

Siguientes pasos