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

# Best Practices

> Best Practices für Enterprise-Umgebungen zum Organisieren von Blueprints, Verwalten von Secrets, Überwachen von Builds, Pinning und zur Migration im großen Maßstab.

Devin unternehmensweit einzusetzen bedeutet, Umgebungen für Dutzende von Organisationen und Hunderte von Repositories zu verwalten. Diese Seite zeigt, welche Muster sich im großen Maßstab bewähren und welche Fehler vermieden werden sollten.

<div id="organizing-blueprints-across-tiers">
  ## Blueprints über Ebenen hinweg organisieren
</div>

Die häufigste Frage von Enterprise-Admins lautet: „Wo sollte diese Konfiguration hin?“

Die Antwort ist einfach: **Legen Sie sie standardmäßig im Enterprise-Blueprint ab.** Der Enterprise-Blueprint ist der richtige Ort für alles, was für alle Organisationen gilt (oder gelten könnte). Dazu gehören Laufzeitumgebungen für Programmiersprachen, Sicherheitstools, Unternehmenszertifikate, interne CLIs, Proxy-Konfigurationen und die Authentifizierung für gemeinsam genutzte Registries. Es ist völlig in Ordnung, hier mehrere Programmiersprachen und Tools zu installieren, auch wenn nicht jede Organisation sie alle nutzt.

| Blueprint-Ebene  | Wann sie verwendet werden sollte                                      | Beispiele                                                                                                                                             |
| ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**   | Standard für alle gemeinsam genutzten Konfigurationen                 | Python 3.12, Node 20, Go 1.22, Rust, Sicherheitsscanner, Unternehmens-CA-Zertifikate, interne CLIs, Proxy-Konfigurationen, gemeinsame Registry-Tokens |
| **Organization** | Nur wenn etwas **nicht** für jede Organisation gelten soll            | Eine teamspezifische private Registry, auf bestimmte Teams beschränkte Tools, org-spezifische Linting-Konfiguration                                   |
| **Repository**   | Repo-spezifische Einrichtung, die im Repo-Verzeichnis ausgeführt wird | `npm install`, `uv sync`, projektspezifische Knowledge-Einträge, `.envrc`-Dateien auf Repo-Ebene                                                      |

**Der einzige Grund, einen Org-Blueprint statt des Enterprise-Blueprints zu verwenden,** ist, wenn Sie ausdrücklich nicht möchten, dass etwas auf jede Organisation angewendet wird. Wenn zum Beispiel ein Team eine private npm-Registry verwendet, auf die andere Teams keinen Zugriff haben sollen, gehört diese Registry-Konfiguration in den Org-Blueprint dieses Teams und nicht in den Enterprise-Blueprint.

Wenn etwas für alle Organisationen gilt, gehört es in den Enterprise-Blueprint. Wenn es repo-spezifisch ist, gehört es in den Repo-Blueprint. Die Org-Ebene existiert nur für die Ausnahmen dazwischen.

<Warning>
  Platzieren Sie keine repo-spezifischen Befehle (wie `npm install`) im Enterprise- oder Org-Blueprint. Diese Ebenen werden im Home-Verzeichnis ausgeführt, nicht im Repo-Verzeichnis, daher schlagen repo-spezifische Befehle fehl oder
  werden am falschen Ort installiert.
</Warning>

<div id="use-knowledge-items-at-the-right-tier">
  ### Verwenden Sie Knowledge-Einträge auf der richtigen Ebene
</div>

Knowledge-Einträge sind über alle Ebenen hinweg kumulativ. Devin sieht sie alle. Nutzen Sie dies, um Vorgaben nach Ebenen zu staffeln:

* **Knowledge auf Enterprise-Ebene**: Unternehmensweite Coding-Standards, Anforderungen an Sicherheitsprüfungen, Links zur internen Dokumentation.
* **Knowledge auf Org-Ebene**: Teamkonventionen, Nutzungsmuster für gemeinsam genutzte Bibliotheken, teamspezifische Deployment-Verfahren.
* **Knowledge auf Repo-Ebene**: Lint-, Test- und Build-Befehle für das jeweilige Projekt.

<div id="secrets-management-at-scale">
  ## Secrets-Verwaltung in großem Maßstab
</div>

Secrets werden entlang derselben Ebenenhierarchie wie Blueprints vererbt, wobei spezifischere Secrets Vorrang haben.

<div id="where-to-define-secrets">
  ### Wo Secrets definiert werden
</div>

| Secret scope     | Verwenden für                                   | Beispiele                                                                                                               |
| ---------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Enterprise**   | Zugangsdaten, die von allen orgs genutzt werden | Tokens für interne Registries, Proxy-Authentifizierung im Unternehmensnetzwerk, gemeinsame API keys für interne Dienste |
| **Organization** | Team-spezifische Zugangsdaten                   | Deployment-Schlüssel für Teams, API-Tokens für Team-Dienste, team-spezifische Registry-Authentifizierung                |
| **Repository**   | Repo-spezifische Zugangsdaten                   | API keys pro Projekt, projektspezifische Service Accounts                                                               |

**Legen Sie Secrets auf der höchsten passenden Ebene ab.** Wenn jede org Zugriff auf die interne npm-Registry benötigt, definieren Sie das Token einmal als Enterprise-Secret. Duplizieren Sie es nicht über 50 org-Konfigurationen hinweg.

<div id="secret-hygiene">
  ### Secret-Hygiene
</div>

* **Speichern Sie Secrets niemals in YAML.** Verwenden Sie immer die Secrets-Verwaltungsoberfläche. Secrets in YAML landen in Logs, Build-Artefakten und Audit-Trails.
* **Rotieren Sie Secrets regelmäßig.** Wenn Sie ein Secret in der UI rotieren, wird der neue Wert beim nächsten Build wirksam. Es sind keine Änderungen am Blueprint erforderlich.
* **Verwenden Sie aussagekräftige Namen.** `INTERNAL_NPM_TOKEN` ist besser als `TOKEN_1`. Andere Admins (und auch Sie selbst in Zukunft) müssen verstehen, wofür jedes Secret gedacht ist.
* **Überprüfen Sie die Verwendung von Secrets.** Prüfen Sie regelmäßig, welche Secrets vorhanden sind und ob sie noch benötigt werden. Entfernen Sie nicht verwendete Secrets, um Ihre Angriffsfläche zu verringern.

<Info>
  Wenn ein org-Secret und ein Enterprise-Secret denselben Namen haben, hat das org-Secret Vorrang. Dasselbe gilt für Repo-Secrets, die org-Secrets überschreiben. Verwenden Sie dies gezielt. Zum Beispiel kann eine org das
  Enterprise-Registry-Token mit einem teamspezifischen Token überschreiben, das andere Berechtigungen hat.
</Info>

<div id="build-health-monitoring">
  ## Überwachung des Build-Status
</div>

Im Unternehmensmaßstab sind fehlgeschlagene Builds unvermeidlich. Entscheidend ist, sie frühzeitig zu erkennen und schnell zu beheben.

<div id="establish-a-review-cadence">
  ### Legen Sie einen regelmäßigen Prüfzyklus fest
</div>

Überprüfen Sie den Build-Status wöchentlich in allen Organisationen. Achten Sie auf Folgendes:

* **Fehlgeschlagene Builds**: Kritische Fehler in Blueprints auf Enterprise- oder Organisationsebene, die alle Repos blockieren.
* **Teilweise fehlgeschlagene Builds**: Bei einigen Repos schlägt der Build fehl. Das ist oft ein Hinweis auf ein Abhängigkeitsproblem oder einen veralteten Blueprint.
* **Veraltete Builds**: Organisationen, deren letzter Build ungewöhnlich lange zurückliegt, was auf eine blockierte Build-Warteschlange hindeuten kann.

<div id="respond-to-enterprise-blueprint-failures">
  ### Auf Fehler bei Enterprise-Blueprints reagieren
</div>

Wenn eine Änderung an einem Enterprise-Blueprint großflächige Fehler verursacht:

1. **Bewerten Sie den Umfang der Auswirkungen.** Prüfen Sie auf der Rollout-Seite, wie viele Orgs betroffen sind.
2. **Setzen Sie den Enterprise-Blueprint** auf den zuletzt bekannten funktionierenden Blueprint zurück. Speichern Sie sofort. Dadurch werden in allen betroffenen Orgs Neubuilds ausgelöst.
3. **Untersuchen Sie den Fehler isoliert.** Testen Sie Ihre Änderungen mit einer einzelnen Pilot-Org, bevor Sie sie erneut ausrollen.

Lassen Sie keinen fehlerhaften Enterprise-Blueprint während der Fehlersuche aktiv. Solange er fehlerhaft ist, erhalten Orgs weiterhin fehlgeschlagene Builds.

<div id="partial-builds-are-a-signal">
  ### Teilweise erfolgreiche Builds sind ein Signal
</div>

Ein teilweise erfolgreicher Build bedeutet, dass einige Repos in einer Org erfolgreich waren, während andere fehlgeschlagen sind. Das wird in der Regel verursacht durch:

* Ein Repo-spezifisches Abhängigkeitsproblem (defekte Lockdatei, entferntes Paket)
* Eine fehlende Systembibliothek, die nur ein Projekt benötigt
* Einen veralteten Blueprint, der nicht an Änderungen im Repo angepasst wurde

Teilweise erfolgreiche Builds erzeugen weiterhin nutzbare Snapshots für die Repos, die erfolgreich waren. Gehen Sie den Fehlern aber nach. Wenn sie ignoriert werden, häufen sie sich in der Regel an.

<div id="when-to-pin-builds">
  ## Wann Sie Builds anpinnen sollten
</div>

Durch das Anpinnen von Builds wird die Umgebung einer Organisation auf einen bestimmten Snapshot eingefroren. Verwenden Sie dies gezielt.

<div id="good-reasons-to-pin">
  ### Gute Gründe zum Anpinnen
</div>

* **Kritisches Release läuft.** Sie benötigen für die nächsten 48 Stunden eine stabile, zuverlässig funktionierende Umgebung, während Sie ein Release ausliefern.
* **Aktive Fehlersuche.** Sie untersuchen ein Problem mit einem Build und möchten nicht, dass automatische Updates in der Zwischenzeit etwas verändern.
* **Rollback.** Ein neuer Build hat eine Regression verursacht, und Sie müssen sofort auf die vorherige Version zurückgehen, während Sie den Blueprint korrigieren.

<div id="bad-reasons-to-pin">
  ### Schlechte Gründe für das Pinnen
</div>

* **Eine Fehlerbehebung zu vermeiden.** Wenn ein Build fehlerhaft ist, beheben Sie das Problem im Blueprint. Das Pinnen kaschiert das Problem, und da Pins nicht automatisch ablaufen, kann ein vergessener Pin dazu führen, dass Sie unbegrenzt in einer veralteten Umgebung arbeiten.
* **„Nur für alle Fälle.“** Automatische Updates halten Abhängigkeiten aktuell und erkennen Probleme frühzeitig. Sie ohne konkreten Grund zu deaktivieren, verzögert Probleme nur.

<Warning>
  Sie können nur Builds anpinnen, die weniger als **7 Tage alt** sind. Nach dem Anpinnen bleibt der Pin aktiv, bis er manuell entfernt wird. Er läuft nicht ab. Ein vergessener Pin bedeutet, dass Ihr Team mit einem
  zunehmend veralteten Snapshot arbeitet.
</Warning>

<div id="migrating-your-enterprise">
  ## Ihr Enterprise-Konto migrieren
</div>

Den empfohlenen Leitfaden für die schrittweise Migration (von den ersten Tests bis zur vollständigen Einführung) finden Sie unter [Ihr Enterprise-Konto migrieren](/de/enterprise/environment-management/rollout#recommended-migration-playbook).

<div id="common-architectural-patterns">
  ## Gängige Architekturmuster
</div>

Unterschiedliche Unternehmensstrukturen machen unterschiedliche Blueprint-Strategien erforderlich.

<div id="monorepo-organizations">
  ### Monorepo-Orgs
</div>

**Setup**: Eine Org mit einem einzigen großen Repository, das mehrere Projekte enthält.

**Ansatz**: Der **Enterprise-Blueprint** deckt das gesamte gemeinsam genutzte Tooling ab (Laufzeitumgebungen, globale CLI-Tools, Registries). Hinterlegen Sie das projektspezifische Setup (`npm install` im Frontend-Verzeichnis, `uv sync` im Backend-Verzeichnis) im **Repo-Blueprint**. Der Org-Blueprint wird nur benötigt, wenn diese Org Tools oder Konfigurationen hat, die nicht für andere Orgs gelten sollen.

Verwenden Sie einen einzelnen Blueprint mit Subshells, um mehrere Projekte zu verwalten:

```yaml theme={null}
# Repo-Blueprint für ein 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">
  ### Organisationen mit mehreren Repos
</div>

**Einrichtung**: Eine Organisation mit mehreren zusammenhängenden Repositorys (z. B. ein Microservices-Team).

**Ansatz**: Platzieren Sie gemeinsam genutzte Tooling- und Registry-Konfigurationen im **Org-Blueprint**. Jedes Repo hat einen eigenen Blueprint, der nur `maintenance` und `Knowledge` enthält. So müssen Einrichtungsbefehle nicht in mehreren Repos dupliziert werden.

<div id="shared-infrastructure-org">
  ### Org für gemeinsame Infrastruktur
</div>

**Setup**: Eine Plattform- oder DevOps-Org, die gemeinsam genutzte Dienste für andere Teams bereitstellt.

**Ansatz**: Der **Enterprise-Blueprint** deckt die gemeinsame Basis ab. Der Blueprint der Org für gemeinsame Infrastruktur installiert plattformspezifische Tools (Terraform, kubectl, Cloud-CLIs), die ihre Repos benötigen. Andere Orgs erhalten diese Tools nicht. Sie bekommen nur das, was im Enterprise-Blueprint enthalten ist, plus ihre eigene Org-Konfiguration.

<div id="isolated-project-orgs">
  ### Isolierte Projekt-Organisationen
</div>

**Einrichtung**: Unabhängige Teams ohne gemeinsam genutzte Tools, abgesehen von den Grundlagen.

**Ansatz**: Das **Enterprise-Blueprint** deckt weiterhin die gemeinsame Basis ab: alle Ihre Standard-Sprachruntimes, Sicherheitstools und die Unternehmensinfrastruktur. Jede Org verwendet ihr eigenes Blueprint nur für Tools oder Konfigurationen, die wirklich nur für dieses Team relevant sind und nicht mit anderen geteilt werden sollten. Repo-Blueprints übernehmen die projektspezifische Einrichtung.

<Info>
  Im Zweifel gehört es in das Enterprise-Blueprint. Wenn eine Org einen bestimmten Grund hat, etwas auszuschließen (etwa inkompatible Tool-Versionen oder eingeschränkter Zugriff), kann sie dies auf Org-Ebene überschreiben. Es ist
  einfacher, eine umfassende Enterprise-Ausgangsbasis zu haben, als die Einrichtung über viele Org-Blueprints hinweg zu duplizieren.
</Info>