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

# Buenas prácticas

> Buenas prácticas para Enterprise al organizar blueprints, gestionar secretos, supervisar compilaciones, fijar versiones y realizar migraciones a escala.

Implementar Devin en una empresa implica gestionar entornos para decenas de organizaciones y cientos de repositorios. En esta página se describen los patrones que mejor funcionan a escala y los errores que conviene evitar.

<div id="organizing-blueprints-across-tiers">
  ## Organizar blueprints por nivel
</div>

La pregunta más común que hacen los administradores de Enterprise es: "¿Dónde debe ir esta configuración?"

La respuesta es simple: **ponla en el blueprint de Enterprise de forma predeterminada.** El blueprint de Enterprise es el lugar adecuado para todo lo que se aplique (o pueda aplicarse) a todas las organizaciones. Esto incluye entornos de ejecución, herramientas de seguridad, certificados corporativos, CLIs internos, configuración de proxy y autenticación compartida para registros. Está perfectamente bien instalar múltiples lenguajes y herramientas aquí, aunque no todas las org los usen todos.

| Nivel de blueprint | Cuándo usarlo                                                   | Ejemplos                                                                                                                                                              |
| ------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**     | Predeterminado para toda la configuración compartida            | Python 3.12, Node 20, Go 1.22, Rust, escáneres de seguridad, certificados de AC corporativa, CLIs internos, configuración de proxy, tokens compartidos para registros |
| **Organization**   | Solo cuando algo **no** deba aplicarse a todas las org          | Un registro privado específico de un equipo, herramientas restringidas a ciertos equipos, configuración de linting específica de la org                               |
| **Repository**     | Configuración por repo que se ejecuta en el directorio del repo | `npm install`, `uv sync`, elementos de Knowledge específicos del proyecto, archivos `.envrc` a nivel de repo                                                          |

**La única razón para usar un blueprint de org en lugar del blueprint de Enterprise** es cuando expresamente no quieres que algo se aplique a todas las organizaciones. Por ejemplo, si un equipo usa un registro privado de npm al que otros equipos no deberían tener acceso, esa configuración del registro debe ir en el blueprint de org de ese equipo, no en el blueprint de Enterprise.

Si algo se aplica a todas las orgs, va en Enterprise. Si es específico del repo, va en el blueprint del repo. El nivel de org existe solo para las excepciones intermedias.

<Warning>
  No pongas comandos específicos del repo (como `npm install`) en el blueprint de Enterprise ni en el de org. Esos niveles se ejecutan en el directorio de inicio, no en el directorio del repo, por lo que los comandos específicos del repo fallarán o
  se instalarán en el lugar equivocado.
</Warning>

<div id="use-knowledge-items-at-the-right-tier">
  ### Usa los elementos de Knowledge en el nivel correcto
</div>

Los elementos de Knowledge se acumulan entre niveles. Devin los ve todos. Úsalo para organizar la orientación por capas:

* **Knowledge de Enterprise**: Estándares de codificación de toda la empresa, requisitos de revisión de seguridad y enlaces a documentación interna.
* **Knowledge de la org**: Convenciones del equipo, patrones de uso de bibliotecas compartidas y procedimientos de despliegue específicos del equipo.
* **Knowledge del repo**: Comandos de lint, pruebas y compilación para el proyecto específico.

<div id="secrets-management-at-scale">
  ## Gestión de secretos a escala
</div>

Los secretos siguen la misma jerarquía de niveles que los blueprints, y los secretos más específicos tienen prioridad.

<div id="where-to-define-secrets">
  ### Dónde definir los secretos
</div>

| Ámbito del secreto | Se usa para                                             | Ejemplos                                                                                                              |
| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**     | Credenciales compartidas entre todas las organizaciones | Tokens del registro interno, autenticación en el proxy corporativo, claves de API compartidas para servicios internos |
| **Organización**   | Credenciales específicas del equipo                     | Claves de despliegue del equipo, tokens de API para servicios del equipo, autenticación en el registro del equipo     |
| **Repositorio**    | Credenciales específicas del repositorio                | Claves de API por proyecto, cuentas de servicio específicas del proyecto                                              |

**Coloca los secretos en el nivel más alto que corresponda.** Si todas las organizaciones necesitan acceso al registro interno de npm, define el token una sola vez como un secreto de Enterprise. No lo dupliques en la configuración de 50 organizaciones.

<div id="secret-hygiene">
  ### Gestión segura de secretos
</div>

* **Nunca incluyas secretos en YAML.** Usa siempre la interfaz de gestión de secretos. Los secretos en YAML acaban en los registros, los artefactos de compilación y los registros de auditoría.
* **Rota los secretos con regularidad.** Cuando rotas un secreto en la interfaz, el nuevo valor entra en vigor en la siguiente compilación. No hace falta cambiar el blueprint.
* **Usa nombres descriptivos.** `INTERNAL_NPM_TOKEN` es mejor que `TOKEN_1`. Otros administradores (y tu yo del futuro) necesitan comprender para qué sirve cada secreto.
* **Audita el uso de los secretos.** Revisa periódicamente qué secretos existen y si siguen siendo necesarios. Elimina los secretos que no se usen para reducir la superficie de ataque.

<Info>
  Si un secreto de la organización y un secreto de Enterprise tienen el mismo nombre, prevalece el secreto de la organización. Lo mismo ocurre cuando los secretos del repositorio reemplazan a los de la organización. Usa este comportamiento de forma intencional. Por ejemplo, una organización podría reemplazar el
  token del registro de Enterprise por un token específico del equipo con permisos diferentes.
</Info>

<div id="build-health-monitoring">
  ## Supervisión del estado de las compilaciones
</div>

A escala empresarial, los fallos de compilación son inevitables. La clave está en detectarlos pronto y resolverlos con rapidez.

<div id="establish-a-review-cadence">
  ### Establece una frecuencia de revisión
</div>

Revisa semanalmente el estado de las compilaciones en todas las organizaciones. Busca lo siguiente:

* **Compilaciones fallidas**: Fallos críticos en los blueprints de Enterprise o de las orgs que bloquean todos los repos.
* **Compilaciones parciales**: Algunos repos fallan. Suele ser señal de un problema de dependencias o de un blueprint desactualizado.
* **Compilaciones desactualizadas**: Orgs cuya compilación más reciente es inusualmente antigua, lo que puede indicar que la cola de compilación está atascada.

<div id="respond-to-enterprise-blueprint-failures">
  ### Responde a los fallos del blueprint de Enterprise
</div>

Si un cambio en el blueprint de Enterprise provoca fallos generalizados:

1. **Evalúa el alcance del impacto.** Comprueba cuántas organizaciones se ven afectadas en la página Rollout.
2. **Revierte el blueprint de Enterprise** al último blueprint que se sabe que funciona correctamente. Guarda de inmediato. Esto activa recompilaciones en todas las organizaciones afectadas.
3. **Investiga de forma aislada.** Prueba tus cambios en una sola organización piloto antes de volver a implementarlos.

No dejes un blueprint de Enterprise roto mientras depuras. Cada minuto que sigue roto, las organizaciones reciben compilaciones fallidas.

<div id="partial-builds-are-a-signal">
  ### Las compilaciones parciales son una señal
</div>

Una compilación parcial significa que algunos repositorios de una org se completaron correctamente mientras que otros fallaron. Esto suele deberse a lo siguiente:

* Un problema de dependencias específico de un repositorio (archivo de bloqueo dañado, paquete eliminado)
* Falta una biblioteca del sistema que solo necesita un proyecto
* Un blueprint desactualizado que no se ha ajustado a los cambios del repositorio

Las compilaciones parciales siguen generando instantáneas utilizables para los repositorios que se completaron correctamente. Pero investiga los fallos. Tienden a acumularse si se ignoran.

<div id="when-to-pin-builds">
  ## Cuándo fijar compilaciones
</div>

Fijar compilaciones congela el entorno de una organización en una instantánea específica. Hazlo deliberadamente.

<div id="good-reasons-to-pin">
  ### Buenas razones para fijar compilaciones
</div>

* **Lanzamiento crítico en curso.** Necesitas un entorno estable y validado durante las próximas 48 horas mientras lanzas una versión.
* **Depuración activa.** Estás investigando un problema de compilación y no quieres que las actualizaciones automáticas cambien nada en pleno proceso.
* **Reversión.** Una nueva compilación introdujo una regresión y necesitas revertirla de inmediato mientras corriges el blueprint.

<div id="bad-reasons-to-pin">
  ### Malas razones para fijar
</div>

* **Evitar una solución.** Si una compilación está rota, corrige el blueprint. Fijarla oculta el problema y, como las fijaciones no caducan automáticamente, una fijación olvidada puede hacer que sigas ejecutando un entorno obsoleto indefinidamente.
* **"Por si acaso."** Las actualizaciones automáticas mantienen las dependencias al día y detectan los problemas pronto. Desactivarlas sin ningún motivo específico solo retrasa los problemas.

<Warning>
  Solo puedes fijar compilaciones de menos de **7 días de antigüedad**. Una vez fijada, la fijación sigue activa hasta que se quite manualmente. No caduca. Una fijación olvidada significa que tu equipo está ejecutando una instantánea cada vez más obsoleta.
</Warning>

<div id="migrating-your-enterprise">
  ## Migrar tu empresa
</div>

Para consultar el playbook recomendado para una migración por fases (desde las pruebas iniciales hasta el despliegue completo), consulta [Migrar tu empresa](/es/enterprise/environment-management/rollout#recommended-migration-playbook).

<div id="common-architectural-patterns">
  ## Patrones de arquitectura comunes
</div>

Las distintas estructuras empresariales requieren diferentes enfoques de blueprint.

<div id="monorepo-organizations">
  ### Organizaciones monorepo
</div>

**Configuración**: Una org con un único repositorio grande que contiene múltiples proyectos.

**Enfoque**: La **blueprint de Enterprise** se encarga de todas las herramientas compartidas (runtimes, herramientas CLI globales, registries). Coloca la configuración específica de cada proyecto (`npm install` en el directorio del frontend, `uv sync` en el directorio del backend) en la **blueprint del repo**. La blueprint de org solo es necesaria si esta org tiene herramientas o configuración que no deberían aplicarse a otras orgs.

Usa una sola blueprint con subshells para gestionar múltiples proyectos:

```yaml theme={null}
# Repo blueprint para un monorepo
maintenance:
  - name: "Frontend dependencies"
    run: (cd frontend && npm install)

  - name: "Backend dependencies"
    run: (cd backend && uv sync)

knowledge:
  - name: lint
    contents: |
      Frontend: cd frontend && npm run lint
      Backend: cd backend && uv run ruff check .
```

<div id="multi-repo-organizations">
  ### Organizaciones con varios repositorios
</div>

**Configuración**: Una org con varios repositorios relacionados (p. ej., un equipo de microservicios).

**Enfoque**: Coloca las herramientas compartidas y la configuración del registro en el **blueprint de la org**. Cada repo tiene su propio blueprint con solo `maintenance` y `Knowledge`. Esto evita duplicar comandos de configuración entre repositorios.

<div id="shared-infrastructure-org">
  ### Org de infraestructura compartida
</div>

**Configuración**: Un org de plataforma o de DevOps que proporciona servicios compartidos que usan otros equipos.

**Enfoque**: El **blueprint de Enterprise** cubre la base común. El blueprint del org de infraestructura compartida instala las herramientas específicas de la plataforma (Terraform, kubectl y CLI de nube) que necesitan sus repos. Los demás orgs no reciben estas herramientas. Solo obtienen lo que incluye el blueprint de Enterprise, además de la configuración de su propio org.

<div id="isolated-project-orgs">
  ### Organizaciones de proyecto aisladas
</div>

**Configuración**: Equipos independientes sin herramientas compartidas más allá de lo básico.

**Enfoque**: El **blueprint Enterprise** sigue encargándose de la base común: todos tus entornos de ejecución estándar, herramientas de seguridad y la infraestructura corporativa. Cada organización usa su propio blueprint solo para herramientas o configuraciones que sean realmente exclusivas de ese equipo y no deban compartirse con otros. Los blueprints del repositorio se encargan de la configuración de cada proyecto.

<Info>
  En caso de duda, inclúyelo en el blueprint Enterprise. Si una organización tiene un motivo específico para excluir algo (versiones de herramientas en conflicto, acceso restringido), puede anularlo a nivel de la organización. Es
  más fácil contar con una base de referencia Enterprise completa que duplicar la configuración en muchos blueprints de organización.
</Info>