Git-basierte Blueprints

Überblick

Git-basierte Blueprints ermöglichen es Ihnen, Ihre Umgebungskonfiguration direkt in Ihrem Repository als Datei .devin/blueprint.yaml zu speichern. Sie synchronisieren die Datei per API oder über die UI mit Devin und lösen dann einen Snapshot-Build aus, um die Änderungen zu übernehmen. So erhalten Sie denselben Workflow wie für Anwendungscode: in Ihrer IDE bearbeiten, einen Pull Request (PR) öffnen, ein Review einholen, zusammenführen und anschließend per CI-Schritt oder über die UI synchronisieren und bauen.

Ansatz	Wo das Blueprint liegt	Wie Sie es bearbeiten	Wie Änderungen übernommen werden
Datenbank (Standard)	Devins Settings-UI	Im Browser bearbeiten	Wird beim Klick sofort gespeichert
Git-basiert	`.devin/blueprint.yaml` in Ihrem Repo	In Ihrer IDE bearbeiten, eine PR zusammenführen	Die Sync-API aufrufen (oder in der UI auf Sync klicken) und dann einen Build auslösen

Git-basierte Blueprints verwenden dasselbe YAML-Format wie der UI-Editor. Die vollständige Feldspezifikation finden Sie in der Blueprint reference.

Erste Schritte

1. Blueprint-Datei erstellen

Fügen Sie im Stammverzeichnis Ihres Repositorys eine .devin/blueprint.yaml-Datei hinzu:

my-repo/
  .devin/
    blueprint.yaml
  src/
  package.json
  ...

Die Datei verwendet dasselbe YAML-Format wie der UI-Editor:

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. In den Standard-Branch pushen

Committen und pushen Sie .devin/blueprint.yaml in den Standard-Branch Ihres Repositorys (in der Regel main oder master). Wenn das Repository bereits mit Devins Environment verbunden ist, müssen Sie eine Synchronisierung anstoßen (über die API oder die UI-Schaltfläche „Sync“), damit Devin die Datei übernimmt. Wenn Sie das Repo zum ersten Mal hinzufügen, wird das Blueprint bei der ersten Erkennung aus Git gelesen.

3. In der UI prüfen

Gehe zu Settings > Environment > Blueprints und klicke auf das Repository. Der Editor zeigt den Inhalt des Blueprints aus Git an, und die Quellenanzeige zeigt den Anbieternamen (z. B. „GitHub“) zusammen mit der synchronisierten Commit-SHA an.

Wie Sync funktioniert

Beim Sync wird .devin/blueprint.yaml vom HEAD des Standard-Branches des Repos abgerufen und die in Devin gespeicherten Blueprint-Versionen werden aktualisiert. Sync erfolgt nicht automatisch bei einem Push — Sie lösen ihn explizit aus:

API-Sync — Rufen Sie den v3-Sync-Endpunkt auf (siehe unten Sync über die API). Dies ist der empfohlene Ansatz für CI/CD-Pipelines.
UI-Sync — Klicken Sie im Blueprint-Editor auf die Schaltfläche Sync. Dadurch wird auch ein Snapshot-Build ausgelöst, wenn sich der Inhalt geändert hat.
Beim Hinzufügen eines Repos zur Umgebung — Wenn .devin/blueprint.yaml im Standard-Branch vorhanden ist, wird das Blueprint bei der ersten Erkennung automatisch aus Git übernommen.

Sync ist idempotent: Wenn sich der Dateiinhalt seit dem letzten Sync nicht geändert hat, wird keine neue Version erstellt.

Sync vs. Build

Sync und Build sind getrennte Vorgänge:

Sync holt die neueste .devin/blueprint.yaml aus Git und speichert eine neue Blueprint-Version.
Build erstellt aus den aktuellen Blueprint-Versionen ein neues Snapshot-Image.

Die Sync-Schaltfläche in der UI führt beide Schritte mit einer einzigen Aktion aus. In der v3-API sind sie getrennt, damit Sie die volle Kontrolle haben — führen Sie zuerst einen Sync aus und lösen Sie dann einen Build aus.

Über die API synchronisieren

Blueprints hält man am besten synchron, indem man nach dem Zusammenführen von Änderungen an .devin/blueprint.yaml die v3 API aufruft. Das geschieht in der Regel in einer CI/CD-Pipeline (z. B. in einem GitHub Actions-Schritt nach dem Merge).

Durchgängiger Ablauf

Schritt 1: Blueprint synchronisieren

Laden Sie die aktuelle .devin/blueprint.yaml aus dem Standard-Branch herunter:

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"}'

Antwort:

{"repo_name": "owner/repo"}

Das Feld repo_name akzeptiert für GitHub owner/repo und für andere Hosts eine vollständige URL (z. B. https://gitlab.com/org/repo).

Schritt 2: Einen Build auslösen

Lösen Sie nach der Synchronisierung einen Snapshot-Build aus, um den neuen Blueprint anzuwenden:

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 '{}'

Antwort:

{
  "build_id": "sbj-abc123",
  "status": "running",
  "trigger": "api",
  "created_at": 1718000000,
  "updated_at": 1718000000
}

Schritt 3: Build-Status pollen (optional)

Wenn Sie warten möchten, bis der Build in CI abgeschlossen ist:

curl https://api.devin.ai/v3/organizations/{org_id}/snapshot-setup/builds/{build_id} \
  -H "Authorization: Bearer $DEVIN_API_TOKEN"

Das Feld status durchläuft folgende Zustände: running → succeeded oder failed.

Unternehmensweite Synchronisierung

Für Enterprises mit mehreren Organisationen, die dasselbe Repository gemeinsam nutzen, gibt es einen Endpunkt auf Enterprise-Ebene, mit dem alle Organisationen synchronisiert werden, die mit dem Repo verbunden sind:

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"}'

Die Antwort enthält die Anzahl synchronisierter orgs:

{"repo_name": "owner/repo", "org_count": 3}

Beispiel: GitHub Actions workflow

Automatisieren Sie Sync + Build bei jedem Push auf den Standard-Branch, der die Blueprint-Datei verändert:

# .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 '{}'

Sie benötigen einen Service-Benutzer oder einen Personal Access Token mit Schreibberechtigungen für die Umgebung. Speichern Sie das Token als DEVIN_API_TOKEN und Ihre Org-ID als DEVIN_ORG_ID in den Secrets Ihres Repositorys.

Git-basierte Blueprints bearbeiten

Wenn ein Blueprint git-basiert ist, ist der UI-Editor für direktes Speichern schreibgeschützt. Stattdessen haben Sie zwei Möglichkeiten, Änderungen vorzunehmen:

Eine PR im Editor erstellen

Öffnen Sie den Blueprint-Editor unter Settings > Environment > Blueprints
Bearbeiten Sie das YAML im Editor
Klicken Sie auf Create PR
Devin eröffnet in Ihrem Repository einen Pull Request, der .devin/blueprint.yaml aktualisiert
Prüfen Sie die PR, genehmigen Sie sie und führen Sie sie zusammen
Die nächste Synchronisierung übernimmt die Änderung und löst einen Build aus

Das ist praktisch für schnelle Änderungen, ohne die Devin-UI zu verlassen.

Direkt in Ihrem Repository bearbeiten

Bearbeiten Sie .devin/blueprint.yaml in Ihrer IDE oder auf Ihrem Git-Anbieter
Committen und pushen Sie in den Standard-Branch (oder öffnen Sie eine Pull Request (PR) und mergen Sie sie)
Lösen Sie eine Synchronisierung über die API aus oder klicken Sie in der UI auf Sync

Dies ist der Standard-Workflow für Teams, die Infrastructure as Code verwalten. Kombinieren Sie ihn mit einem CI-Schritt, um die Synchronisierung zu automatisieren (siehe Über die API synchronisieren).

Devin-Vorschläge

Wenn Devin während einer Sitzung eine Blueprint-Änderung vorschlägt (z. B. nach der Analyse Ihres Projekts), wird dieser Vorschlag als PR für .devin/blueprint.yaml umgesetzt, statt direkt in der Datenbank gespeichert zu werden. Sie prüfen die PR und mergen sie wie jede andere Codeänderung.

Monorepos und Workspaces

Für Monorepos mit mehreren Packages können Sie die Direktive includes verwenden, um für jeden Workspace ein separates Blueprint zu definieren. Jeder Workspace erhält in seinem Unterverzeichnis eine eigene Datei .devin/blueprint.yaml.

Root-Blueprint mit Includes

Die Root-Datei .devin/blueprint.yaml legt fest, welche Workspaces eigene Blueprints haben:

# my-repo/.devin/blueprint.yaml
includes:
  - packages/frontend
  - packages/backend

initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

Workspace-Blueprints

Jeder eingebundene Workspace hat eine eigene .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

Regeln für `includes`

Jeder includes-Eintrag ist ein Pfad zu einem Unterverzeichnis (z. B. packages/frontend). Devin sucht in diesem Verzeichnis nach .devin/blueprint.yaml.
Sie können auch den vollständigen Pfad verwenden: packages/frontend/.devin/blueprint.yaml.
Nur das Root-Blueprint darf includes enthalten. Verschachtelte includes (ein eingebundenes Blueprint, das selbst includes deklariert) sind nicht zulässig.
Jeder Workspace-Pfad darf in includes nur einmal vorkommen.
Fehlt eine eingebundene Datei im Repository, wird der entsprechende Workspace als entfernt behandelt und sein Blueprint bereinigt.

Zwischen Git- und Datenbankmodus umschalten

Zu Git wechseln

Wenn Sie bereits ein datenbankgestütztes Blueprint haben und zu Git wechseln möchten:

Erstellen Sie .devin/blueprint.yaml mit den gewünschten Inhalten in Ihrem Repository.
Pushen Sie die Änderungen in den Standard-Branch.
Klicken Sie im Blueprint-Editor auf das Dropdown-Menü „Quelle“ und wählen Sie Ihren Git-Anbieter aus (z. B. „GitHub“).
Devin synchronisiert die Datei aus Git und wechselt in den Git-basierten Modus.

Zum Datenbankmodus wechseln

Wenn du den git-basierten Modus nicht mehr verwenden und das Blueprint in der UI verwalten möchtest:

Klicke im Blueprint-Editor auf das Dropdown-Menü „Quelle“ und wähle Database aus.
Der aktuelle Inhalt bleibt erhalten, aber zukünftige Pushes an .devin/blueprint.yaml aktualisieren das Blueprint nicht mehr.
Du kannst das Blueprint jetzt direkt in der UI bearbeiten und speichern.

Wenn du das Root-Blueprint in den Datenbankmodus umschaltest, werden auch alle Workspace-Blueprints für dieses Repo in den Datenbankmodus umgeschaltet, da die Synchronisierung auf Repo-Ebene erfolgt.

Entkoppelte Workspaces

Sie können einzelne Workspace-Blueprints von Git entkoppeln, während das Root im Git-basierten Modus bleibt. Ein entkoppelter Workspace kann in der UI bearbeitet werden und wird bei der Synchronisierung übersprungen. Das ist nützlich, wenn ein Workspace vorübergehend eine abweichende Konfiguration benötigt, ohne den Rest des Repos zu beeinträchtigen. Um einen entkoppelten Workspace wieder anzubinden, setzen Sie seine Quelle im Dropdown-Menü „Quelle“ wieder auf Git.

Versionsverlauf

Bei jeder Synchronisierung wird im Versionsverlauf des Blueprints eine neue Version erstellt, gekennzeichnet mit:

Quelle: git_sync für Versionen, die durch die Synchronisierung erstellt wurden, manual für Versionen, die in der UI erstellt wurden
Commit-SHA: der Commit des Standard-Branches, für den die Synchronisierung ausgeführt wurde (mit Link zum Commit bei Ihrem Git-Anbieter)

Den vollständigen Versionsverlauf und die Diffs können Sie auf der Registerkarte Versionsverlauf im Blueprint-Editor anzeigen.

YAML mit mehreren Dokumenten

Wie im UI-Editor unterstützt .devin/blueprint.yaml YAML mit mehreren Dokumenten mithilfe des Trennzeichens ---. So können Sie plattformspezifische Konfigurationen in einer einzigen Datei definieren:

# Linux-Konfiguration (Standard)
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

Siehe Windows-Support für Details zu plattformübergreifenden Blueprints.

Fehlerbehebung

Blueprint wird nicht synchronisiert

Befindet sich die Datei unter dem richtigen Pfad? Sie muss sich unter .devin/blueprint.yaml im Root-Verzeichnis des Repositorys befinden (oder unter <workspace>/.devin/blueprint.yaml für eingebundene Workspaces).
Haben Sie eine Synchronisierung ausgelöst? Die Synchronisierung erfolgt nicht automatisch bei einem Push. Rufen Sie den Sync-API-Endpunkt auf oder klicken Sie in der UI auf die Schaltfläche Sync.
Ist das Repository in Devins Umgebung? Das Repo muss unter Settings > Environment > Blueprints hinzugefügt werden, damit die Synchronisierung ausgeführt werden kann.
Ist der git-basierte-Modus aktiviert? Der Blueprint muss sich im git-basierten-Modus befinden (nicht im Datenbankmodus), damit die Synchronisierung ihn aktualisiert.

Fehler durch ungültiges YAML

Wenn .devin/blueprint.yaml ungültiges YAML enthält oder nicht dem Blueprint-Schema entspricht, schlägt die Synchronisierung mit einer Fehlermeldung fehl. Korrigieren Sie die Datei im Standard-Branch und synchronisieren Sie sie dann erneut. Der Blueprint-Editor in der UI validiert das Schema und zeigt Fehler an, bevor Sie eine PR erstellen. So lassen sich Probleme erkennen, bevor sie in den Standard-Branch gelangen.

Blueprint zeigt nach dem Pushen „Database“ an

Wenn Sie eine .devin/blueprint.yaml gepusht haben, im Editor aber weiterhin „Database“ als Quelle angezeigt wird, wurde das Blueprint möglicherweise noch nicht in den git-basierten Modus umgeschaltet. Verwenden Sie das Dropdown-Menü „Quelle“, um zu Ihrem Git-Anbieter zu wechseln. Dadurch wird die erste Synchronisierung ausgelöst.

​Überblick

​Erste Schritte

​1. Blueprint-Datei erstellen

​2. In den Standard-Branch pushen

​3. In der UI prüfen

​Wie Sync funktioniert

​Sync vs. Build

​Über die API synchronisieren

​Durchgängiger Ablauf

​Schritt 1: Blueprint synchronisieren

​Schritt 2: Einen Build auslösen

​Schritt 3: Build-Status pollen (optional)

​Unternehmensweite Synchronisierung

​Beispiel: GitHub Actions workflow

​Git-basierte Blueprints bearbeiten

​Eine PR im Editor erstellen

​Direkt in Ihrem Repository bearbeiten

​Devin-Vorschläge

​Monorepos und Workspaces

​Root-Blueprint mit Includes

​Workspace-Blueprints

​Regeln für includes

​Zwischen Git- und Datenbankmodus umschalten

​Zu Git wechseln

​Zum Datenbankmodus wechseln

​Entkoppelte Workspaces

​Versionsverlauf

​YAML mit mehreren Dokumenten

​Fehlerbehebung

​Blueprint wird nicht synchronisiert

​Fehler durch ungültiges YAML

​Blueprint zeigt nach dem Pushen „Database“ an

Überblick

Erste Schritte

1. Blueprint-Datei erstellen

2. In den Standard-Branch pushen

3. In der UI prüfen

Wie Sync funktioniert

Sync vs. Build

Über die API synchronisieren

Durchgängiger Ablauf

Schritt 1: Blueprint synchronisieren

Schritt 2: Einen Build auslösen

Schritt 3: Build-Status pollen (optional)

Unternehmensweite Synchronisierung

Beispiel: GitHub Actions workflow

Git-basierte Blueprints bearbeiten

Eine PR im Editor erstellen

Direkt in Ihrem Repository bearbeiten

Devin-Vorschläge

Monorepos und Workspaces

Root-Blueprint mit Includes

Workspace-Blueprints

Regeln für `includes`

Zwischen Git- und Datenbankmodus umschalten

Zu Git wechseln

Zum Datenbankmodus wechseln

Entkoppelte Workspaces

Versionsverlauf

YAML mit mehreren Dokumenten

Fehlerbehebung

Blueprint wird nicht synchronisiert

Fehler durch ungültiges YAML

Blueprint zeigt nach dem Pushen „Database“ an