> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprints basados en Git

> Almacena blueprints como .devin/blueprint.yaml en tu repositorio y sincronízalos a través de la API o la UI.

<div id="overview">
  ## Resumen
</div>

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                                                                   |
| ---------------------------------- | ---------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Base de datos (predeterminado)** | La UI de Settings de Devin         | Editarlo en el navegador                 | Se guarda inmediatamente al hacer clic                                                        |
| **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 |

<Info>
  Los blueprints basados en Git usan el mismo formato YAML que el editor de la UI. Consulta la [Blueprint reference](/es/onboard-devin/environment/blueprint-reference) para ver la especificación completa de los campos.
</Info>

<div id="getting-started">
  ## Primeros pasos
</div>

<div id="1-create-the-blueprint-file">
  ### 1. Crear el archivo blueprint
</div>

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:

```yaml theme={null}
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
```

<div id="2-push-to-the-default-branch">
  ### 2. Haz push a la rama predeterminada
</div>

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.

<div id="3-verify-in-the-ui">
  ### 3. Verificar en la UI
</div>

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.

<div id="how-sync-works">
  ## Cómo funciona la sincronización
</div>

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](#sync-via-the-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.

<div id="sync-vs-build">
  ### Sync vs. compilación
</div>

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.

<div id="sync-via-the-api">
  ## Sincronización mediante la API
</div>

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).

<div id="end-to-end-flow">
  ### Flujo de principio a fin
</div>

```mermaid theme={null}
sequenceDiagram
    participant Dev as Developer
    participant Git as Git Provider
    participant CI as CI/CD Pipeline
    participant API as Devin API
    Dev->>Git: Push/merge .devin/blueprint.yaml
    Git->>CI: Trigger post-merge workflow
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/sync
    API-->>CI: 200 OK (repo_name)
    CI->>API: POST /v3/organizations/{org_id}/snapshot-setup/builds
    API-->>CI: 201 Created (build_id, status)
    CI->>API: GET /v3/organizations/{org_id}/snapshot-setup/builds/{build_id}
    API-->>CI: 200 OK (status: succeeded)
```

<div id="step-1-sync-the-blueprint">
  ### Paso 1: Sincroniza el blueprint
</div>

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

```bash theme={null}
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:

```json theme={null}
{"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`).

<div id="step-2-trigger-a-build">
  ### Paso 2: Iniciar una compilación
</div>

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

```bash theme={null}
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:

```json theme={null}
{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}
```

<div id="step-3-poll-build-status-optional">
  ### Paso 3: Consultar el estado de la compilación (opcional)
</div>

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

```bash theme={null}
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`.

<div id="enterprise-wide-sync">
  ### Sincronización a nivel Enterprise
</div>

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:

```bash theme={null}
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:

```json theme={null}
{"repo_name": "owner/repo", "org_count": 3}
```

<div id="example-github-actions-workflow">
  ### Ejemplo: flujo de trabajo de GitHub Actions
</div>

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

```yaml theme={null}
# .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 '{}'
```

<Info>
  Necesitas un [usuario de servicio](/es/api-reference/overview) 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.
</Info>

<div id="editing-git-backed-blueprints">
  ## Edición de blueprints basados en Git
</div>

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:

<div id="create-a-pr-from-the-editor">
  ### Crear una PR desde el editor
</div>

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.

<div id="edit-directly-in-your-repository">
  ### Edita directamente en tu repositorio
</div>

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](#sync-via-the-api)).

<div id="devin-suggestions">
  ### Sugerencias de Devin
</div>

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.

<div id="monorepos-and-workspaces">
  ## Monorepos y espacios de trabajo
</div>

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.

<div id="root-blueprint-with-includes">
  ### Blueprint raíz con inclusiones
</div>

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

```yaml theme={null}
# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install
```

<div id="workspace-blueprints">
  ### Blueprints de espacios de trabajo
</div>

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

```yaml theme={null}
# my-repo/packages/frontend/.devin/blueprint.yaml
maintenance: |
  pnpm build

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

```yaml theme={null}
# my-repo/packages/backend/.devin/blueprint.yaml
maintenance: |
  pip install -r requirements.txt

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

<div id="include-rules">
  ### Reglas de inclusión
</div>

* 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.

<div id="switching-between-git-and-database-modes">
  ## Cambiar entre los modos Git y de base de datos
</div>

<div id="switch-to-git">
  ### Cambiar a Git
</div>

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

<div id="switch-to-database">
  ### Cambiar al modo de base de datos
</div>

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

<Warning>
  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.
</Warning>

<div id="detached-workspaces">
  ### Espacios de trabajo desvinculados
</div>

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.

<div id="version-history">
  ## Historial de versiones
</div>

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.

<div id="multi-document-yaml">
  ## YAML multidocumento
</div>

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:

```yaml theme={null}
# 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](/es/onboard-devin/environment/windows-support) para obtener más información sobre los blueprints multiplataforma.

<div id="troubleshooting">
  ## Solución de problemas
</div>

<div id="blueprint-not-syncing">
  ### La plantilla no se sincroniza
</div>

* **¿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.

<div id="invalid-yaml-errors">
  ### Errores de YAML inválido
</div>

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.

<div id="blueprint-shows-database-after-pushing">
  ### La plantilla muestra "Database" después de hacer push
</div>

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.