Workspaces und Monorepos

Monorepos und Workspaces mit mehreren Paketen erfordern bei Blueprints besondere Sorgfalt, da in verschiedenen Unterverzeichnissen unterschiedliche Sprachen, Paketmanager oder Abhängigkeiten verwendet werden können. Devin unterstützt zwei Ansätze:

Native Workspaces (empfohlen)

Erstellen Sie für jedes Unterverzeichnis einen separaten Blueprint. Jeder Workspace erhält eigene Abschnitte für initialize und Maintenance, wobei das Arbeitsverzeichnis automatisch auf das jeweilige Unterverzeichnis gesetzt wird.

Subshells

Führen Sie Befehle in Unterverzeichnissen innerhalb eines einzelnen Blueprints mit (cd dir && command) aus. Einfacher für kleine Monorepos mit nur wenigen Paketen.

Native Workspaces

Für die meisten Monorepos empfohlen. Native Workspaces geben jedem Unterverzeichnis einen eigenen Blueprint mit isoliertem Setup und Arbeitsverzeichnis. Das ist übersichtlicher und leichter zu warten als subshells, wenn die Anzahl der Packages wächst.

Bei Native Workspaces erhält jedes Unterverzeichnis einen dedizierten Blueprint. Befehle in diesem Blueprint werden ausgeführt, wobei das Arbeitsverzeichnis bereits auf das Unterverzeichnis gesetzt ist — cd oder subshells sind nicht nötig.

Der Root-Blueprint

Jedes Repo, das native Workspaces verwendet, sollte ein Root-Blueprint haben. Der Root-Blueprint wird im Root-Verzeichnis des Repo ausgeführt, und zwar vor allen Workspace-spezifischen Blueprints. Verwenden Sie ihn für gemeinsames Setup, das im gesamten Repo gilt — etwa zum Installieren von Runtimes, globalen Tools oder zum Ausführen von Abhängigkeitsinstallationen im Root-Verzeichnis.

# Root-Blueprint — wird zuerst ausgeführt, vom Repo-Root aus
initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Workspace-Blueprints übernehmen dann das paketspezifische Setup und werden nach Abschluss des Root-Blueprints ausgeführt.

Einen Workspace erstellen

Gehen Sie zu Settings > Environment > Blueprints
Klicken Sie auf das Repository
Klicken Sie auf Workspace hinzufügen
Geben Sie den Pfad des Unterverzeichnisses ein (z. B. packages/frontend)
Erstellen Sie das Blueprint für diesen Workspace

Der Workspace-Pfad muss einem tatsächlichen Verzeichnis innerhalb des Repositorys entsprechen. Wenn der Pfad beim Ausführen des Builds nicht existiert, schlägt der Build fehl. Prüfen Sie sorgfältig, dass der Pfad exakt mit Ihrer Repo-Struktur übereinstimmt (z. B. packages/frontend, nicht pkg/frontend).

Beispiel

Ein Monorepo mit einem React-Frontend und einem Python-Backend. Im Root-Blueprint werden gemeinsam genutzte Tools installiert, anschließend verwaltet jeder Workspace seine eigenen Abhängigkeiten:

Root
packages/frontend
packages/backend

# Root-Blueprint — gemeinsames Setup für das gesamte Repo
initialize: |
  npm install -g pnpm
  curl -LsSf https://astral.sh/uv/install.sh | sh

knowledge:
  - name: structure
    contents: |
      Monorepo mit zwei Packages:
      - packages/frontend — React-App (TypeScript, pnpm)
      - packages/backend — Python-API (FastAPI, uv)

# Workspace mit Geltungsbereich packages/frontend
maintenance: |
  pnpm install

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

# Workspace mit Geltungsbereich packages/backend
maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest
  - name: dev
    contents: uv run uvicorn app.main:app --reload

Die knowledge-Einträge jedes Workspaces sind auf dieses Unterverzeichnis beschränkt. Wenn Devin in packages/frontend arbeitet, sieht es die Frontend-Befehle für Linting, Tests und Entwicklung — nicht die für das Backend.

Wann native Workspaces sinnvoll sind

Unterverzeichnisse haben unterschiedliche Sprachen oder Paketmanager
Jedes Paket benötigt eigene Knowledge-Einträge (Lint-, Test- und Build-Befehle)
Sie möchten ein isoliertes Setup — ein fehlerhaftes Blueprint für einen Workspace blockiert die anderen nicht
Die Anzahl der Pakete wächst, und ein einzelnes Blueprint wird zunehmend unübersichtlich

Subshells

Bei einfacheren Monorepos können Sie alles in einem einzigen Blueprint mithilfe von Subshells verwalten. Schließen Sie Befehle in Klammern ein, um sie in einem Unterverzeichnis auszuführen, ohne dass sich dies auf nachfolgende Schritte auswirkt:

maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)

Die Klammern (cd ... && ...) erzeugen eine Subshell. Wenn die Subshell beendet wird, wird das Arbeitsverzeichnis für den nächsten Schritt wieder auf das Stammverzeichnis des Repos gesetzt.

Ohne Klammern ändert cd das Arbeitsverzeichnis für alle folgenden Schritte. Verwende beim Wechseln von Verzeichnissen in Blueprint-Schritten immer Subshells.

Warum Subshells wichtig sind

Vergleichen Sie diese beiden Ansätze:

Korrekt (Subshells)
Falsch (keine Subshells)

maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)

Jeder Schritt wird vom Stammverzeichnis des Repos aus ausgeführt. Beide Befehle finden das richtige Unterverzeichnis packages/.

maintenance:
  - name: Frontend deps
    run: cd packages/frontend && pnpm install
  - name: Backend deps
    run: cd packages/backend && uv sync

Im ersten Schritt wird in das Arbeitsverzeichnis packages/frontend gewechselt. Im zweiten Schritt wird dann versucht, cd packages/backend relativ zu packages/frontend auszuführen, was fehlschlägt.

Wann Sie Subshells verwenden sollten

Das Monorepo hat wenige Pakete mit einfachem Setup
Alle Pakete nutzen dieselbe Sprache und denselben Paketmanager
Sie benötigen keine Knowledge-Einträge pro Paket

Knowledge-Einträge für Monorepos

Unabhängig davon, ob Sie native Workspaces oder Subshells nutzen – gut strukturierte Knowledge-Einträge helfen Devin dabei, sich in der Codebasis zurechtzufinden:

knowledge:
  - name: structure
    contents: |
      This is a monorepo with three packages:
      - `packages/frontend` — React app (TypeScript, pnpm)
      - `packages/backend` — Python API (FastAPI, uv)
      - `packages/shared` — Shared TypeScript utilities
  - name: frontend
    contents: |
      cd packages/frontend
      Dev server: pnpm dev
      Lint: pnpm lint
      Test: pnpm test
  - name: backend
    contents: |
      cd packages/backend
      Dev server: uv run uvicorn app.main:app --reload
      Lint: uv run ruff check .
      Test: uv run pytest

Ein structure-Knowledge-Eintrag, der jedem Verzeichnis seine Sprache und Toolchain zuordnet, hilft Devin, sich schnell im Repo zurechtzufinden. Bei nativen Workspaces hat jeder Workspace seine eigenen Knowledge-Einträge, sodass der Eintrag structure im Root-Blueprint oder bei subshell-basierten Setups am nützlichsten ist.

Beispiele

Turborepo / Nx Workspace

Für Workspaces, die mit einem Monorepo-Build-Tool wie Turborepo oder Nx verwaltet werden, installieren Sie die Abhängigkeiten im Stammverzeichnis, und lassen Sie das Tool die Orchestrierung für die einzelnen Packages übernehmen:

initialize: |
  npm install -g pnpm turbo

maintenance: |
  pnpm install

knowledge:
  - name: structure
    contents: |
      Turborepo monorepo. Use `turbo` for building and testing:
      - `apps/web` — Next.js app
      - `apps/api` — Express API
      - `packages/ui` — Shared component library
      - `packages/config` — Shared configuration
  - name: build
    contents: turbo run build
  - name: test
    contents: turbo run test
  - name: lint
    contents: turbo run lint
  - name: dev
    contents: turbo run dev

Mehrere JDK-Versionen

Ein Java-Monorepo, in dem verschiedene Dienste unterschiedliche JDK-Versionen benötigen:

initialize:
  - name: Install JDK 17 (primary)
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install JDK 11 (legacy service)
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-11-jdk-headless

maintenance:
  - name: Warm dependency caches
    run: |
      export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
      (cd services/api && ./gradlew dependencies --refresh-dependencies)

      export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
      (cd services/legacy && ./gradlew dependencies --refresh-dependencies)

knowledge:
  - name: build_api
    contents: |
      Build the API service (JDK 17):
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        cd services/api && ./gradlew clean build
  - name: build_legacy
    contents: |
      Build the legacy service (JDK 11):
        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        cd services/legacy && ./gradlew clean build
  - name: test_all
    contents: |
      Run tests for all services:
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        (cd services/api && ./gradlew test)

        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        (cd services/legacy && ./gradlew test)

Blueprint auf Organisationsebene für gemeinsam genutzte Tools

Wenn mehrere Pakete in einem Monorepo dieselben Tools verwenden, installieren Sie diese einmal im organisationsweiten Blueprint:

# Organisationsweites Blueprint (Settings > Environment > Blueprints > Org-wide setup)
initialize:
  - name: Install pnpm
    run: npm install -g pnpm
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install shared build tools
    run: npm install -g turbo typescript

Dann braucht jedes Repo-Blueprint nur noch projektspezifische Befehle:

# Repo Blueprint (verwendet pnpm und uv aus dem Org Blueprint)
maintenance:
  - name: Install all workspace deps
    run: pnpm install
  - name: Install Python service deps
    run: (cd services/ml-pipeline && uv sync)

Best Practices

Native Workspaces für komplexe Monorepos bevorzugen

Wenn jedes Unterverzeichnis eine eigene Sprache, einen eigenen Paketmanager oder einen eigenen Build-Prozess hat, bleibt mit nativen Workspaces jedes Blueprint fokussiert und unabhängig. Subshells solltest du einfachen Fällen mit wenigen Paketen vorbehalten.

Für Verzeichniswechsel immer Subshells verwenden

Wenn du den Subshell-Ansatz verwendest, setze cd-Befehle in Klammern: (cd dir && command). So verhinderst du, dass sich der Verzeichniswechsel eines Schritts auf den nächsten auswirkt.

Gemeinsam genutzte Tools im Organisations-Blueprint ablegen

Sprachlaufzeitumgebungen und Paketmanager, die in mehreren Repo verwendet werden, gehören in das organisationsweite Blueprint. So vermeidest du Duplikate und hältst Repo-Blueprints auf das projektspezifische Setup fokussiert.

Maintenance-Schritte nach Abhängigkeiten anordnen

Wenn Paket A davon abhängt, dass Paket B zuerst gebaut wird, führe den Build-Schritt von B in maintenance vor dem Installationsschritt von A auf. Blueprint-Schritte werden in der angegebenen Reihenfolge nacheinander ausgeführt.

Einen Eintrag für die Struktur hinzufügen

Ein Eintrag mit dem Namen structure, der Verzeichnisse ihren Sprachen und Tools zuordnet, hilft Devin, sich in der Codebase zurechtzufinden. Gib an, welchen Paketmanager jedes Unterverzeichnis verwendet und welche paketübergreifenden Abhängigkeiten es gibt.

Einträge pro Paket verwenden

Erstelle statt eines großen Eintrags separate Einträge für jedes Paket (z. B. frontend, backend, ml-pipeline). Bei nativen Workspaces hat jeder Workspace bereits einen integrierten eigenen Bereich.

Maintenance inkrementell halten

Verwende pnpm install (nicht pnpm install --force) und uv sync (nicht rm -rf .venv && uv sync). Inkrementelle Befehle sind bei regelmäßigen Rebuilds schneller.

Deklarative Umgebungskonfiguration
Blueprint-Referenz
Vorlagenbibliothek — enthält einsatzbereite Monorepo-Vorlagen

Native Workspaces (empfohlen)

Subshells

​Native Workspaces

​Der Root-Blueprint

​Einen Workspace erstellen

​Beispiel

​Wann native Workspaces sinnvoll sind

​Subshells

​Warum Subshells wichtig sind

​Wann Sie Subshells verwenden sollten

​Knowledge-Einträge für Monorepos

​Beispiele

​Turborepo / Nx Workspace

​Mehrere JDK-Versionen

​Blueprint auf Organisationsebene für gemeinsam genutzte Tools

​Best Practices

​Verwandte Seiten

Native Workspaces

Der Root-Blueprint

Einen Workspace erstellen

Beispiel

Wann native Workspaces sinnvoll sind

Subshells

Warum Subshells wichtig sind

Wann Sie Subshells verwenden sollten

Knowledge-Einträge für Monorepos

Beispiele

Turborepo / Nx Workspace

Mehrere JDK-Versionen

Blueprint auf Organisationsebene für gemeinsam genutzte Tools

Best Practices

Verwandte Seiten