Configuración declarativa

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.

¿Sigues usando la configuración clásica? Puedes migrar a la configuración declarativa en cualquier momento. Devin puede encargarse de gran parte de la migración por ti. Consulta Migración a la configuración declarativa.

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

Lo mejor para la mayoría de los usuarios. Devin analiza tu proyecto, identifica qué herramientas y dependencias hacen falta y genera el blueprint por ti. Tú solo tienes que revisarlo y aprobarlo.

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 repo.”

Revisa y aprueba

Devin propone un blueprint. Verás tarjetas de sugerencias en tu línea de tiempo. Revísalas y haz clic en Approve.

Verifica

Cuando finalice la compilación, inicia una nueva sesión. 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 confirmar que todo funciona.

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 del entorno

Ve a Settings > Environment > Blueprints en la barra lateral de tu organización.Si no ves esta opción, es posible que tu organización todavía esté usando la configuración clásica. Consulta Migración a la configuración declarativa para empezar.

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 entorno 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 blueprints. 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 (normalmente, entre 2 y 10 minutos). Puedes seguir el progreso en Settings > Environment > Snapshots, en Current build.

Verifica

Cuando la compilación muestre Success, 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 en detalle la ruta manual. También es útil para comprender lo que generó Devin si usaste la ruta recomendada.

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 entorno 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, además de un bloque 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.
`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. 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 Knowledge.

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 > configuración de la organización	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.

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 ejecutando tus blueprints en secuencia:

1. Enterprise blueprint, if configured (runs in ~):
   a. initialize
   b. maintenance
2. Org blueprint (runs in ~):
   a. initialize
   b. maintenance
3. Clone all repositories (up to 10 concurrent).
   Each repo's blueprint may override clone defaults via the
   `clone` block (branch/tag, depth, submodules, LFS, etc.).
4. For each configured repo, in the order shown in Settings
   (runs in ~/repos/<repo-name>):
   a. initialize
   b. maintenance
5. Health check, then snapshot is saved

Las capas son acumulativas: los comandos específicos del repo pueden usar herramientas instaladas por la organización o el blueprint de Enterprise. Los niveles inferiores no pueden anular lo que configuró un nivel superior. Las compilaciones suelen tardar entre 5 y 15 minutos. Los pasos individuales tienen un tiempo de espera de 1 hora.

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 repo) 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 repo se cargan en el contexto de Devin.

Knowledge es específico de cada repo. Si tienes 5 repos configurados, Devin solo ve las entradas de Knowledge del repo 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
Éxito	Todos los pasos se completaron. La instantánea está lista.
Parcial	Algunos pasos a nivel de repo fallaron, pero la instantánea se puede usar. Los repos que se completaron correctamente funcionan con normalidad; los repos que fallaron requieren corregir sus blueprints.
Fallida	Error crítico (falló la configuración de la org o de Enterprise). La instantánea no se puede usar.
Cancelada	Fue reemplazada por una compilación más reciente o se canceló manualmente.

Una compilación parcial sigue generando una instantánea funcional. Si uno de cinco repos tiene un blueprint dañado, los otros cuatro son completamente funcionales.

¿Está fallando la compilación? Consulta Solución de problemas de compilaciones para obtener 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 repo tiene su propio blueprint. Durante una compilación, todos los repos se configuran en la misma instantánea, se clonan en directorios separados y sus dependencias se instalan de forma independiente. Si dos repos 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 correcta 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) y haz clic en Pin. Mientras esté anclada, se omiten las actualizaciones periódicas y la interfaz muestra Auto-updates paused. Para desanclar: Haz clic en Resume auto-updates. Devin cambia a la compilación correcta 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 hay 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 tiene un tiempo límite de 1 hora. 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

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 repo como .devin/blueprint.yaml y sincronízalos mediante la API o la UI.

Migración desde la configuración clásica

Guía paso a paso para pasar del asistente interactivo a los blueprints declarativos.

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

​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

Compilaciones diferenciales

GitHub Actions en blueprints

Workspaces y monorepos

referencia de Blueprint

Biblioteca de plantillas

Blueprints respaldados por Git

Migración desde la configuración clásica

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