Blueprints basados en Git

Resumen

Los blueprints basados en Git te permiten almacenar la configuración de tu entorno directamente en tu repositorio como un archivo .devin/blueprint.yaml. Sincronizas el archivo con Devin mediante la API o la UI, y luego activas una compilación de instantánea para aplicar los cambios. Esto te da el mismo workflow que usas para el código de la aplicación: editar en tu IDE, abrir un pull request, obtener una revisión, hacer merge y luego sincronizar + compilar mediante un paso de CI o desde la UI.

Enfoque	Dónde está el blueprint	Cómo lo editas	Cómo se aplican los cambios
Basado en Git	`.devin/blueprint.yaml` en tu repo	Editarlo en tu IDE, hacer merge de un PR	Llama a la API de sincronización (o haz clic en Sync en la UI) y luego activa una compilación, o bien activa la opción de sincronizar y compilar en cada commit a la rama predeterminada
Base de datos	La UI de Settings de Devin	Editarlo en el navegador	Se guarda inmediatamente al hacer clic

Cómo Devin elige el modo cuando agregas un repositorio

El modo basado en Git es el predeterminado siempre que haya un archivo de blueprint en el repo. Cuando agregas un repositorio a tu entorno, Devin comprueba si en la rama predeterminada existe .devin/blueprint.yaml:

Si el archivo existe, Devin obtiene el blueprint desde Git (modo basado en Git) y registra el SHA del commit desde el que sincronizó.
Si el archivo no existe (o la detección falla), Devin crea un blueprint vacío que gestionas en la UI de Settings (modo de base de datos).

Puedes cambiar un repositorio entre los dos modos en cualquier momento — consulta Cambiar entre los modos Git y base de datos.

Los blueprints basados en Git usan el mismo formato YAML que el editor de la UI. Consulta la blueprint reference para ver la especificación completa de los campos.

Primeros pasos

Crear el archivo blueprint

Agrega un archivo .devin/blueprint.yaml en la raíz de tu repositorio:

my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...

El archivo usa el mismo formato YAML que el editor de la interfaz de usuario:

initialize:
  - name: Install Node.js 22
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

maintenance:
  - name: Install dependencies
    run: npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test

Haz push a la rama predeterminada

Confirma y haz push de .devin/blueprint.yaml a la rama predeterminada de tu repositorio (normalmente main o master). Si el repositorio ya está conectado al Environment de Devin, debes iniciar una sincronización (mediante la API o el botón Sync de la UI) para que Devin detecte el archivo, a menos que el blueprint ya esté en modo basado en Git y el repositorio tenga habilitado Run on every commit to default branch. Si el blueprint está en modo de base de datos, cámbialo a Git para importar el archivo. Si estás agregando el repo por primera vez, el descubrimiento inicial lee el blueprint desde Git.

Verificar en la UI

Ve a Settings > Environment > Blueprints y haz clic en el repositorio. El editor muestra el contenido del blueprint de Git, y el indicador de origen muestra el nombre del proveedor (p. ej., “GitHub”) junto con el SHA del commit sincronizado.

Cómo funciona la sincronización

La sincronización es el proceso de obtener .devin/blueprint.yaml del HEAD de la rama predeterminada del repo y actualizar las versiones de blueprint almacenadas en Devin. De forma predeterminada, la sincronización no se realiza automáticamente al hacer push. La sincronización se ejecuta en estos casos:

Sincronización mediante la API — Llama al endpoint de sincronización (beta) (consulta Sincronización mediante la API más abajo). Este es el enfoque recomendado para los pipelines de CI/CD.
Sincronización en la UI — Haz clic en el botón Sync en el editor de blueprint. Esto también activa una compilación de instantánea si el contenido cambió.
Al agregar un repo al Environment — Si .devin/blueprint.yaml existe en la rama predeterminada, el blueprint se obtiene automáticamente desde Git durante la detección inicial.
En cada commit a la rama predeterminada (opcional) — En los repositorios con Run on every commit to default branch habilitado, cada push a la rama predeterminada sincroniza el blueprint y activa una compilación. Consulta Sincronizar y compilar en cada commit de la rama predeterminada.

La sincronización es idempotente: si el contenido del archivo no ha cambiado desde la última sincronización, no se crea ninguna versión nueva.

Sincronización y compilación en cada commit a la rama predeterminada

En repositorios de GitHub.com, puedes optar por la sincronización y las compilaciones automáticas en lugar de llamar a la API desde CI o hacer clic en Sync:

Ve a Settings > Environment > Blueprints y haz clic en el repositorio.
Abre la pestaña Advanced.
Activa Run on every commit to default branch.

Con esta opción activada, cada push a la rama predeterminada sincroniza el blueprint basado en Git y pone en cola una compilación de instantánea para cada plataforma. Si llega un commit más reciente mientras la compilación de uno anterior sigue en cola, esa compilación en cola se cancela para que solo se compile el commit más nuevo; las compilaciones que ya hayan comenzado se ejecutan hasta el final. Si el blueprint del repositorio está en modo base de datos, la compilación usa el blueprint guardado en Devin en lugar del archivo del commit. Activa Report status checks for each commit para mostrar el resultado de cada compilación como un check run de GitHub en el commit.

La pestaña Advanced solo aparece en repositorios de GitHub.com y únicamente cuando esta opción está disponible para tu organización. Para otros Git providers, o cuando la opción está desactivada, usa la sincronización por API o el botón Sync.

Sync vs. compilación

Sync y la compilación son operaciones independientes:

Sync obtiene el archivo .devin/blueprint.yaml más reciente de Git y almacena una nueva versión del blueprint.
Build crea una nueva imagen de instantánea a partir de las versiones actuales del blueprint.

El botón de sincronización de la UI realiza ambos pasos en una sola acción. La API los separa para darte control total: primero llama a sync y luego inicia una compilación.

Sincronización mediante la API

Los endpoints de blueprints y de compilaciones forman parte de la API estable /v3/. Los endpoints de sincronización siguen en beta y se sirven en /v3beta1/; sus rutas y las estructuras de solicitud/respuesta pueden cambiar antes de pasar a /v3/.

Si Run on every commit to default branch no está disponible o está desactivado en tu repositorio, la forma recomendada de mantener los blueprints sincronizados es invocar la API después de fusionar los cambios en .devin/blueprint.yaml. Normalmente, esto se hace desde un pipeline de CI/CD (p. ej., un paso posterior a la fusión en GitHub Actions).

Flujo de principio a fin

Paso 1: Sincroniza el blueprint

Obtén la versión más reciente de .devin/blueprint.yaml de la rama predeterminada:

curl -X POST https://api.devin.ai/v3beta1/organizations/{org_id}/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

Respuesta:

{"repo_name": "owner/repo"}

El campo repo_name acepta owner/repo para GitHub o la URL completa del proveedor para otros hosts (p. ej., https://gitlab.com/org/repo).

Paso 2: Iniciar una compilación

Después de la sincronización, inicia una compilación de instantánea para aplicar el nuevo blueprint:

curl -X POST https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta:

{
  "build_id": "sbj-abc123",
  "status": "pending",
  "trigger": "manual",
  "triggered_by_user_id": "user-abc123",
  "pinned": false,
  "started_at": null,
  "completed_at": null,
  "created_at": 1718000000,
  "updated_at": 1718000000
}

Paso 3: Consultar el estado de la compilación (opcional)

Si quieres esperar a que la compilación finalice en CI:

curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"

El campo status pasa por los siguientes valores: pending → running → succeeded o failed (o cancelled). La API informa una compilación parcial como succeeded porque la instantánea es utilizable.

Sincronización a nivel Enterprise

Para empresas con múltiples organizaciones que comparten el mismo repositorio, hay un endpoint a nivel Enterprise que sincroniza todas las organizaciones con conexión al repositorio:

curl -X POST https://api.devin.ai/v3beta1/enterprise/snapshot-setup/sync \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "owner/repo"}'

La respuesta incluye el número de orgs sincronizadas:

{"repo_name": "owner/repo", "org_count": 3}

Ejemplo: flujo de trabajo de GitHub Actions

Automatiza la sincronización + la compilación con cada push a la rama predeterminada que afecte al archivo blueprint:

# .github/workflows/sync-blueprint.yml
name: Sync Devin Blueprint

on:
  push:
    branches: [main]
    paths:
      - '.devin/blueprint.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync blueprint
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3beta1/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/sync" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"repo_name": "${{ github.repository }}"}'

      - name: Trigger build
        run: |
          curl -sf -X POST \
            "https://api.devin.ai/v3/organizations/${{ secrets.DEVIN_ORG_ID }}/snapshot-setup/builds" \
            -H "Authorization: Bearer ${{ secrets.DEVIN_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{}'

Necesitas un usuario de servicio o un token de acceso personal con permisos de escritura en Environment. Guarda el token como DEVIN_API_TOKEN y tu org ID como DEVIN_ORG_ID en los secretos del repositorio.

Edición de blueprints basados en Git

Cuando un blueprint está basado en Git, el Editor de la interfaz de usuario queda en modo de solo lectura para los guardados directos. En su lugar, tienes dos opciones para hacer cambios:

Crear una PR desde el editor

Abre el editor de blueprint en Settings > Environment > Blueprints
Edita el YAML en el editor
Haz clic en Create PR
Devin abre una pull request en tu repositorio que actualiza .devin/blueprint.yaml
Revisa, aprueba y haz merge de la PR
La siguiente sincronización detecta el cambio y activa una compilación

Esto resulta útil para hacer ediciones rápidas sin salir de la interfaz de Devin.

Edita directamente en tu repositorio

Edita .devin/blueprint.yaml en tu IDE o en tu proveedor de Git
Confirma y haz push a la rama predeterminada (o abre una solicitud de extracción (PR) y fusiónala)
Inicia una sincronización mediante la API o haz clic en Sync en la UI (no es necesario si Run on every commit to default branch está habilitado)

Este es el flujo de trabajo estándar para los equipos que gestionan infraestructura como código. Combínalo con un paso de CI para automatizar la sincronización (consulta Sincronización mediante la API), o habilita la sincronización automática en las confirmaciones a la rama predeterminada.

Sugerencias de Devin

Cuando Devin propone un cambio en el blueprint durante una sesión (p. ej., después de analizar tu proyecto), la sugerencia se aplica abriendo una solicitud de extracción (PR) para .devin/blueprint.yaml en lugar de guardarse directamente en la base de datos. Luego revisas y fusionas la PR como cualquier otro cambio de código.

Monorepos y espacios de trabajo

Para monorepos con múltiples paquetes, puedes usar la directiva includes para definir blueprints independientes para cada espacio de trabajo. Cada espacio de trabajo tiene su propio archivo .devin/blueprint.yaml en su subdirectorio.

Blueprint raíz con inclusiones

El archivo .devin/blueprint.yaml raíz define qué espacios de trabajo tienen sus propios blueprints:

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Blueprints de espacios de trabajo

Cada espacio de trabajo incluido tiene su propio .devin/blueprint.yaml:

# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test

# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

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

Reglas de inclusión

Cada entrada de includes es una ruta de subdirectorio (p. ej., packages/frontend). Devin busca .devin/blueprint.yaml dentro de ese directorio.
También se puede usar la ruta completa: packages/frontend/.devin/blueprint.yaml.
Solo el blueprint raíz puede contener includes. No se permiten inclusiones anidadas (un blueprint incluido que, a su vez, declare includes).
Cada ruta de espacio de trabajo solo puede aparecer una vez en includes.
Si falta un archivo incluido en el repositorio, ese espacio de trabajo se considera eliminado y se elimina su blueprint.

Cambiar entre los modos Git y de base de datos

Cambiar a Git

Si tienes un blueprint existente gestionado en la base de datos y quieres cambiar a Git:

Crea .devin/blueprint.yaml en tu repositorio con el contenido deseado
Haz push a la rama predeterminada
En el editor de blueprint, haz clic en el menú desplegable de origen y selecciona tu proveedor de Git (por ejemplo, “GitHub”)
Devin sincroniza el archivo desde Git y cambia al modo basado en Git

Cambiar al modo de base de datos

Si quieres dejar de usar el modo basado en Git y gestionar el blueprint en la interfaz de usuario:

En el editor de blueprint, haz clic en el menú desplegable de origen y selecciona Database
Se conserva el contenido actual, pero los futuros pushes a .devin/blueprint.yaml ya no actualizarán el blueprint
Ahora puedes editar y guardar directamente en la interfaz de usuario

Cambiar el blueprint raíz al modo de base de datos también cambia todos los blueprints de espacio de trabajo de ese repositorio al modo de base de datos, ya que la sincronización funciona a nivel de repositorio.

Espacios de trabajo desvinculados

Puedes desvincular de Git los blueprints de espacios de trabajo individuales mientras mantienes la raíz en modo basado en Git. Un espacio de trabajo desvinculado se puede editar en la UI y se excluye durante la sincronización. Esto resulta útil cuando un espacio de trabajo necesita una anulación temporal sin afectar al resto del repositorio. Para volver a vincular un espacio de trabajo desvinculado, cambia su origen de nuevo a Git desde el menú desplegable de origen.

Historial de versiones

Cada sincronización crea una nueva versión en el historial del blueprint, etiquetada con:

Origen: git_sync para las versiones creadas por sincronización, manual para las versiones creadas en la interfaz de usuario
SHA del commit: el commit de la rama predeterminada sobre el que se ejecutó la sincronización (enlaza al commit en tu proveedor de Git)

Puedes ver el historial completo de versiones y los diff en la pestaña Historial de versiones del editor de blueprint.

YAML multidocumento

Al igual que el editor de la interfaz de usuario, .devin/blueprint.yaml admite YAML multidocumento con el separador ---. Esto te permite definir configuraciones específicas de la plataforma en un solo archivo:

# Configuración de Linux (predeterminado)
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh

maintenance: |
  uv sync
---
runs-on: windows

initialize: |
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

maintenance: |
  uv sync

Consulta soporte para Windows para obtener más información sobre los blueprints multiplataforma.

Solución de problemas

La plantilla no se sincroniza

¿Está el archivo en la ruta correcta? Debe estar en .devin/blueprint.yaml en la raíz del repositorio (o en <espacio de trabajo>/.devin/blueprint.yaml para los espacios de trabajo incluidos).
¿Iniciaste una sincronización? De forma predeterminada, la sincronización no ocurre automáticamente al hacer push. Llama al endpoint de la API de sincronización o haz clic en el botón Sync en la UI. Si esperas que los push se sincronicen automáticamente, verifica que Run on every commit to default branch esté habilitado en la pestaña Advanced del repositorio y que hayas hecho push a la rama predeterminada.
¿Está el repositorio en el Environment de Devin? La repo debe agregarse en Settings > Environment > Blueprints para que se ejecute la sincronización.
¿Está habilitado el modo basado en Git? El blueprint debe estar en modo basado en Git (no en modo de base de datos) para que la sincronización lo actualice.

Errores de YAML inválido

Si .devin/blueprint.yaml contiene YAML inválido o no se ajusta al esquema del blueprint, la sincronización falla. Corrige el archivo en la rama predeterminada y vuelve a sincronizar. El editor de blueprint en la UI valida el esquema y muestra los errores antes de que crees una PR, lo que ayuda a detectar problemas antes de que lleguen a la rama predeterminada.

La plantilla muestra “Database” después de hacer push

Si hiciste push de un archivo .devin/blueprint.yaml pero el editor sigue mostrando “Database” como origen, puede que el blueprint todavía no se haya cambiado al modo basado en Git. Usa el menú desplegable de origen para cambiar a tu proveedor de Git, lo que activa la sincronización inicial.

​Resumen

​Cómo Devin elige el modo cuando agregas un repositorio

​Primeros pasos

​ Crear el archivo blueprint

​ Haz push a la rama predeterminada

​ Verificar en la UI

​Cómo funciona la sincronización

​Sincronización y compilación en cada commit a la rama predeterminada

​Sync vs. compilación

​Sincronización mediante la API

​Flujo de principio a fin

​Paso 1: Sincroniza el blueprint

​Paso 2: Iniciar una compilación

​Paso 3: Consultar el estado de la compilación (opcional)

​Sincronización a nivel Enterprise

​Ejemplo: flujo de trabajo de GitHub Actions

​Edición de blueprints basados en Git

​Crear una PR desde el editor

​Edita directamente en tu repositorio

​Sugerencias de Devin

​Monorepos y espacios de trabajo

​Blueprint raíz con inclusiones

​Blueprints de espacios de trabajo

​Reglas de inclusión

​Cambiar entre los modos Git y de base de datos

​Cambiar a Git

​Cambiar al modo de base de datos

​Espacios de trabajo desvinculados

​Historial de versiones

​YAML multidocumento

​Solución de problemas

​La plantilla no se sincroniza

​Errores de YAML inválido

​La plantilla muestra “Database” después de hacer push

Resumen

Cómo Devin elige el modo cuando agregas un repositorio

Primeros pasos

Crear el archivo blueprint

Haz push a la rama predeterminada

Verificar en la UI

Cómo funciona la sincronización

Sincronización y compilación en cada commit a la rama predeterminada

Sync vs. compilación

Sincronización mediante la API

Flujo de principio a fin

Paso 1: Sincroniza el blueprint

Paso 2: Iniciar una compilación

Paso 3: Consultar el estado de la compilación (opcional)

Sincronización a nivel Enterprise

Ejemplo: flujo de trabajo de GitHub Actions

Edición de blueprints basados en Git

Crear una PR desde el editor

Edita directamente en tu repositorio

Sugerencias de Devin

Monorepos y espacios de trabajo

Blueprint raíz con inclusiones

Blueprints de espacios de trabajo

Reglas de inclusión

Cambiar entre los modos Git y de base de datos

Cambiar a Git

Cambiar al modo de base de datos

Espacios de trabajo desvinculados

Historial de versiones

YAML multidocumento

Solución de problemas

La plantilla no se sincroniza

Errores de YAML inválido

La plantilla muestra “Database” después de hacer push