Saltar al contenido principal

​
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.
EnfoqueDónde está el blueprintCómo lo editasCómo se aplican los cambios
Base de datos (predeterminado)La UI de Settings de DevinEditarlo en el navegadorSe guarda inmediatamente al hacer clic
Basado en Git.devin/blueprint.yaml en tu repoEditarlo en tu IDE, hacer merge de un PRLlama a la API de sincronización (o haz clic en Sync en la UI) y luego activa una compilación
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

​
1. 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

​
2. 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. Si estás agregando el repo por primera vez, el descubrimiento inicial lee el blueprint desde Git.

​
3. 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. La sincronización no se realiza automáticamente al hacer push; debes activarla explícitamente:
  1. Sincronización mediante la API — Llama al endpoint de sincronización de la v3 (consulta Sincronización mediante la API más abajo). Este es el enfoque recomendado para los pipelines de CI/CD.
  2. 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ó.
  3. 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.
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.

​
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 v3 los separa para darte control total: primero llama a sync y luego inicia una compilación.

​
Sincronización mediante la API

La forma recomendada de mantener los blueprints sincronizados es invocar la API v3 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/v3/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": "running",
  "trigger": "api",
  "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: running → succeeded o failed.

​
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/v3/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/v3/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

  1. Abre el editor de blueprint en Settings > Environment > Blueprints
  2. Edita el YAML en el editor
  3. Haz clic en Create PR
  4. Devin abre una pull request en tu repositorio que actualiza .devin/blueprint.yaml
  5. Revisa, aprueba y haz merge de la PR
  6. 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

  1. Edita .devin/blueprint.yaml en tu IDE o en tu proveedor de Git
  2. Confirma y haz push a la rama predeterminada (o abre una solicitud de extracción (PR) y fusiónala)
  3. Inicia una sincronización mediante la API o haz clic en Sync en la UI
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 Sync via the API).

​
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:
  1. Crea .devin/blueprint.yaml en tu repositorio con el contenido deseado
  2. Haz push a la rama predeterminada
  3. En el editor de blueprint, haz clic en el menú desplegable de origen y selecciona tu proveedor de Git (por ejemplo, “GitHub”)
  4. 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:
  1. En el editor de blueprint, haz clic en el menú desplegable de origen y selecciona Database
  2. Se conserva el contenido actual, pero los futuros pushes a .devin/blueprint.yaml ya no actualizarán el blueprint
  3. 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? 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.
  • ¿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.