Blueprint-Referenz

Dies ist die vollständige Feldreferenz für Blueprints. Eine Einführung in Blueprints und ihre Rolle in Devins Umgebung finden Sie unter Deklarative Umgebungskonfiguration.

Ein Blueprint definiert, wie Devins Umgebung konfiguriert wird: welche Tools installiert werden, wie Abhängigkeiten aktuell gehalten werden und welche Befehle Devin kennen soll.

Überblick

Ein Blueprint besteht aus drei Abschnitten auf oberster Ebene:

initialize: ...   # Tools und Laufzeitumgebungen installieren
maintenance: ...  # Projektabhängigkeiten installieren
knowledge: ...    # Referenzinformationen für Devin (wird nie ausgeführt)

Abschnitt	Zweck	Ausgeführt?
`initialize`	System-Tools, Sprachlaufzeiten und globale CLIs installieren	Ja, bei jedem Build
`maintenance`	Projektabhängigkeiten installieren und aktualisieren	Ja, bei Builds. Dem Agenten zu Sitzungsbeginn als Kontext angezeigt (wird nicht automatisch ausgeführt).
`knowledge`	Devin Anweisungen zum Linten, Testen und Bauen sowie weitere projektspezifische Informationen geben	Nein, nur als Referenz

Alle drei Abschnitte sind optional. Sie können jede beliebige Kombination verwenden. initialize wird nur bei Builds ausgeführt. Die Ergebnisse werden im Snapshot gespeichert. maintenance wird bei Builds (nach initialize) ausgeführt. Zu Beginn jeder Sitzung werden maintenance-Befehle nicht automatisch ausgeführt — stattdessen werden sie dem Agenten als Kontext angezeigt, damit er weiß, welche Befehle für Abhängigkeiten bei Bedarf ausgeführt werden müssen (z. B. nach dem Abrufen des neuesten Codes). Die Befehle sollten weiterhin schnell und inkrementell sein. Builds werden automatisch ausgeführt, wenn sich Ihr Blueprint ändert, und außerdem regelmäßig (ca. alle 24 Stunden).

initialize

Verwende initialize, um Tools und Laufzeitumgebungen zu installieren, die nicht vom konkreten Zustand deines Codes abhängen: Laufzeitumgebungen für Programmiersprachen, Systempakete, globale CLIs.

Einfache Form

Für einfache Shell-Befehle verwenden Sie einen Blockskalar:

initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  apt-get update && apt-get install -y build-essential
  npm install -g pnpm

Strukturierte Form

Verwenden Sie für benannte Schritte, Umgebungsvariablen oder GitHub Actions eine Liste:

initialize:
  - name: "Install Python 3.12"
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: "Install system packages"
    run: |
      apt-get update
      apt-get install -y libpq-dev

  - name: "Install global tools"
    run: pip install uv
    env:
      PIP_BREAK_SYSTEM_PACKAGES: "1"

Beide Formen können kombiniert werden. Die einfache Form entspricht einem einzelnen Schritt mit run.

Wann `initialize` statt `maintenance` verwenden

In `initialize`	In `maintenance` einfügen
Installation der Laufzeitumgebung	`npm install` / `pip install`
Systempakete (`apt-get`)	`bundle install`
Globale CLI-Tools	`go mod download`
Einmalige Konfiguration	Updates des Abhängigkeits-Caches
GitHub Actions (`setup-python`, etc.)	Repo-spezifische Setup-Skripte

Beide Abschnitte werden bei jedem Build ausgeführt, aber die Trennung hält Ihre Konfiguration übersichtlich. Tools und Laufzeitumgebungen gehören in initialize; Abhängigkeitsbefehle, die sich an den Lock-Dateien Ihres Codes orientieren, gehören in maintenance.

maintenance

Verwenden Sie maintenance für die Installation von Abhängigkeiten und andere Befehle, die nach dem Klonen Ihres Codes ausgeführt werden sollen. Diese Befehle werden während Builds ausgeführt und dem Agenten zu Beginn der Sitzung angezeigt, damit er sie erneut ausführen kann, wenn sich Abhängigkeiten geändert haben. Hierhin gehören npm install, pip install, uv sync und ähnliche Befehle.

maintenance: |
  npm install
  pip install -r requirements.txt

Oder in strukturierter Form:

maintenance:
  - name: "Install npm dependencies"
    run: npm install

  - name: "Install Python dependencies"
    run: uv sync
    env:
      UV_CACHE_DIR: /tmp/uv-cache

Für Blueprints auf Repo-Ebene werden maintenance-Befehle im Root-Verzeichnis des Repos ausgeführt. Für Blueprints auf Org-Ebene werden sie im Home-Verzeichnis (~) ausgeführt.

knowledge

Der Abschnitt knowledge wird nicht ausgeführt. Er enthält Referenzinformationen, die Devin bei der Arbeit an Ihrem Projekt verwendet. Hier geben Sie Devin die richtigen Befehle für Linting, Tests, Builds und andere projektspezifische Workflows an.

knowledge:
  - name: lint
    contents: |
      Run linting with:
      npm run lint

      For auto-fix:
      npm run lint -- --fix

  - name: test
    contents: |
      Run the full test suite:
      npm test

      Run a single test file:
      npm test -- path/to/test.ts

  - name: build
    contents: |
      npm run build

      Build output goes to dist/

Jeder Knowledge-Eintrag hat:

Feld	Typ	Beschreibung
`name`	string	Bezeichner für diesen Knowledge-Eintrag (z. B. `lint`, `test`, `build`)
`contents`	string	Freitext mit Befehlen, Anweisungen oder Hinweisen

Das Feld name ist eine Bezeichnung. Üblicherweise sind lint, test und build die Standardnamen. Bei der Überprüfung seiner Arbeit greift Devin auf diese zurück. Sie können beliebige zusätzliche Knowledge-Einträge mit benutzerdefinierten Namen hinzufügen:

knowledge:
  - name: lint
    contents: ...
  - name: test
    contents: ...
  - name: build
    contents: ...
  - name: deploy
    contents: |
      Deploy to staging:
      npm run deploy:staging
  - name: database
    contents: |
      Run migrations:
      npm run db:migrate

      Seed test data:
      npm run db:seed

Schritttypen

Jeder Schritt in initialize oder maintenance gehört zu einem von zwei Typen: Shell-Befehle (run) oder GitHub Actions (uses).

Shell-Befehle (`run`)

Führen Sie beliebige Shell-Befehle in Bash aus:

- name: "Install dependencies"
  run: |
    npm install
    pip install -r requirements.txt

Feld	Typ	Beschreibung
`name`	string (optional)	Menschenlesbare Bezeichnung für den Schritt
`run`	string	Auszuführende Shell-Befehle
`env`	map (optional)	Zusätzliche Umgebungsvariablen für diesen Schritt

Ausführungsdetails:

Befehle werden in bash ausgeführt. Wenn in einem mehrzeiligen Skript ein Befehl fehlschlägt, wird der gesamte Schritt sofort abgebrochen.
Blueprints auf Org-Ebene werden im Home-Verzeichnis (~) ausgeführt.
Blueprints auf Repo-Ebene werden im Root-Verzeichnis des geklonten Repositorys ausgeführt.
Jeder Schritt hat ein Timeout von 1 Stunde.
Secrets sind automatisch als Umgebungsvariablen verfügbar.

GitHub Actions (`uses`)

Führen Sie Node.js-basierte GitHub Actions direkt in Ihrem Blueprint aus:

- name: "Install Python"
  uses: github.com/actions/setup-python@v5
  with:
    python-version: "3.12"

Feld	Typ	Beschreibung
`name`	string (optional)	Menschenlesbare Bezeichnung für den Schritt
`uses`	string	Referenz auf eine GitHub Action
`with`	map (optional)	Eingabeparameter für die Action
`env`	map (optional)	Zusätzliche Umgebungsvariablen für diesen Schritt

Format der Action-Referenz:

github.com/<owner>/<repo>@<ref>
github.com/<owner>/<repo>/<subpath>@<ref>

Das Präfix github.com/ und das Suffix @<ref> sind beide erforderlich. Die Referenz ist in der Regel ein Versions-Tag wie v5. Häufig verwendete Actions:

Action	Zweck	Beispiel für `with`
`github.com/actions/setup-python@v5`	Python installieren	`python-version: "3.12"`
`github.com/actions/setup-node@v4`	Node.js installieren	`node-version: "20"`
`github.com/actions/setup-go@v5`	Go installieren	`go-version: "1.22"`
`github.com/actions/setup-java@v4`	Java/JDK installieren	`java-version: "21"`, `distribution: "temurin"`
`github.com/gradle/actions/setup-gradle@v4`	Gradle installieren	(keine)
`github.com/ruby/setup-ruby@v1`	Ruby installieren	`ruby-version: "3.3"`

Unterstützt werden nur Node.js-basierte GitHub Actions. Composite Actions und Docker-basierte Actions werden nicht unterstützt.

So funktionieren with-Werte: Werte, die über with übergeben werden, werden der Action als Eingaben übergeben und folgen dabei denselben Konventionen wie in GitHub-Actions-Workflows. Alle Werte werden in Zeichenfolgen umgewandelt.

with:
  python-version: "3.12"
  check-latest: true
  cache: "pip"

Wie Aktionen Änderungen weiterreichen: Aktionen können die Umgebung für nachfolgende Schritte ändern. Zum Beispiel fügt setup-python die Python-Binärdatei zu PATH hinzu, sodass sie in allen späteren Schritten und in maintenance verfügbar bleibt.

`run` vs. `uses`: wann Sie was verwenden sollten

`run` verwenden, wenn…	`uses` verwenden, wenn…
Systempakete installiert werden (`apt-get`)	Laufzeitumgebungen für Programmiersprachen eingerichtet werden (Python, Node, Go, Java, Ruby)
projektspezifische Skripte ausgeführt werden	es eine offizielle GitHub Action für Ihre Anforderungen gibt
Dateien oder die Umgebung konfiguriert werden	Sie automatische Versionsverwaltung und Caching nutzen möchten
der Befehl einfach und in sich abgeschlossen ist	Sie dieselbe Action in einem GitHub-Actions-Workflow verwenden würden

In der Praxis verwenden die meisten Konfigurationen uses für Laufzeitumgebungen von Programmiersprachen und run für alles andere.

Umgebungsvariablen und Secrets

Umgebungsvariablen pro Schritt

Jeder Schritt kann mit dem Feld env zusätzliche Umgebungsvariablen definieren:

- run: pip install -r requirements.txt
  env:
    PIP_INDEX_URL: "https://pypi.example.com/simple/"
    PIP_BREAK_SYSTEM_PACKAGES: "1"

Diese gelten nur für den jeweiligen Schritt und bleiben in nachfolgenden Schritten nicht erhalten.

Schrittübergreifende Umgebungsvariablen (`$ENVRC`)

Um Umgebungsvariablen über mehrere Schritte hinweg weiterzugeben, schreiben Sie sie in die Datei $ENVRC:

- name: "Set shared variables"
  run: |
    echo "DATABASE_URL=postgresql://localhost:5432/myapp" >> $ENVRC
    echo "APP_ENV=development" >> $ENVRC

In $ENVRC geschriebene Variablen werden automatisch exportiert und stehen in allen nachfolgenden Schritten sowie in der Devin-Sitzung zur Verfügung. Das funktioniert ähnlich wie $GITHUB_ENV in GitHub Actions.

Secrets

In der Devin-Benutzeroberfläche konfigurierte Secrets (über den Secrets-Tab in jedem Blueprint-Editor) werden automatisch als Umgebungsvariablen eingefügt. Sie müssen sie nicht in Ihrem Blueprint deklarieren. Verweisen Sie einfach per Namen darauf (z. B. $MY_SECRET). Secrets werden vor jedem Schritt während Builds eingefügt und zu Beginn jeder Sitzung erneut eingefügt. Aus dem Snapshot-Image selbst werden sie entfernt, sodass Zugangsdaten niemals in gespeicherte Maschinenabbilder eingebettet sind.

Organisations-Secrets: Als Umgebungsvariablen in jedem Schritt aller Blueprints in der org verfügbar. Konfigurieren Sie diese im Secrets-Tab des Editors für das organisationsweite Blueprint.
Enterprise-Secrets: Werden mit org-Secrets zusammengeführt (bei Namenskonflikten haben org-Secrets Vorrang). In allen orgs im Enterprise verfügbar.
Repository-Secrets: Werden in eine Repo-spezifische Datei unter /run/repo_secrets/{owner/repo}/.env.secrets geschrieben. Während Builds werden Repo-Secrets automatisch geladen, bevor die Blueprint-Schritte dieses Repos ausgeführt werden. Während Sitzungen lädt Devin sie, wenn im Repo gearbeitet wird. Konfigurieren Sie diese im Secrets-Tab des Blueprint-Editors des Repositorys.

Nur-Build-Secrets: Secrets, die als “build only” markiert sind, sind während Snapshot-Builds verfügbar, werden aber entfernt, bevor der Snapshot gespeichert wird. Verwenden Sie diese für Zugangsdaten, die nur während des Builds benötigt werden (z. B. zum Herunterladen privater Artefakte während initialize).

maintenance wird während Builds ausgeführt. Zu Beginn einer Sitzung werden maintenance-Befehle dem Agent angezeigt (nicht automatisch ausgeführt), sodass der Agent sie bei Bedarf erneut ausführen kann. Wenn ein maintenance-Schritt Secrets in Konfigurationsdateien schreibt (z. B. ~/.m2/settings.xml, ~/.npmrc), werden diese Dateien in den Snapshot eingebettet. Platzieren Sie Schritte, die Zugangsdaten schreiben, in maintenance (nicht in initialize), damit sie während periodischer Builds aktualisiert werden. Beachten Sie aber, dass die geschriebenen Dateien im Image erhalten bleiben. Für maximale Sicherheit sollten Sie Umgebungsvariablen oder $ENVRC verwenden, anstatt Zugangsdaten auf den Datenträger zu schreiben.

Dateianhänge

Sie können Dateien (wie .npmrc, settings.xml oder Konfigurationsdateien) über den Blueprint-Editor hochladen. Hochgeladene Dateien werden unter ~/.files/ abgelegt, und es wird eine Umgebungsvariable gesetzt, die auf den Pfad der jeweiligen Datei verweist:

$FILE_SETTINGS_XML    -> /home/ubuntu/.files/settings.xml
$FILE_NPMRC           -> /home/ubuntu/.files/.npmrc

Der Variablenname wird vom Dateinamen abgeleitet: in Großbuchstaben, wobei nicht alphanumerische Zeichen durch Unterstriche ersetzt und mit dem Präfix FILE_ versehen werden. Verwenden Sie Dateianhänge in Ihren Blueprint-Schritten:

maintenance:
  - name: "Configure Maven"
    run: |
      mkdir -p ~/.m2
      cp "$FILE_SETTINGS_XML" ~/.m2/settings.xml

Git-basierte Blueprints

Git-basierte Blueprints werden derzeit nicht unterstützt. Diese Funktion ist in Kürze verfügbar. Sie können Blueprints in Ihrem Repository speichern und Builds automatisch auslösen lassen, wenn sich diese ändern. Konfigurieren Sie Blueprints bis dahin über die UI unter Settings > Environment > Blueprints.

Vollständiges Beispiel

Informationen dazu, wie Blueprints über verschiedene Ebenen hinweg zusammenwirken (enterprise → org → repo), zu Build-Status, Repository-Zuständen und dazu, was einen erneuten Build auslöst, finden Sie unter Builds und Sitzungen auf der Seite zur deklarativen Konfiguration.

Organisationsweites Blueprint

Gemeinsam genutzte Tools, die jedes Repo in der Org benötigt. Dieses Blueprint wird zuerst ausgeführt (nach einem etwaigen Enterprise-Blueprint), und zwar im Home-Verzeichnis.

initialize:
  - name: "Install Node.js 20"
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: "Install Python 3.12 and uv"
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh

  - name: "Install shared tools"
    run: |
      npm install -g pnpm turbo
      apt-get update && apt-get install -y jq ripgrep

  - name: "Configure private registry"
    run: |
      echo "//npm.corp.example.com/:_authToken=$NPM_REGISTRY_TOKEN" >> ~/.npmrc

Blueprint auf Repo-Ebene

Projektspezifische Einrichtung für ein Node.js- und Python-Monorepo. Sie wird nach dem organisationsweiten Blueprint im Repository-Verzeichnis ausgeführt.

initialize:
  - name: "Install Playwright browsers"
    run: npx playwright install --with-deps chromium

  - name: "Set up project environment variables"
    run: |
      echo "DATABASE_URL=postgresql://localhost:5432/myapp_dev" >> $ENVRC
      echo "REDIS_URL=redis://localhost:6379" >> $ENVRC
      echo "APP_ENV=development" >> $ENVRC

maintenance:
  - name: "Install frontend dependencies"
    run: |
      cd frontend
      pnpm install

  - name: "Install backend dependencies"
    run: |
      cd backend
      uv sync

  - name: "Run database migrations"
    run: |
      cd backend
      uv run alembic upgrade head
    env:
      DATABASE_URL: "postgresql://localhost:5432/myapp_dev"

knowledge:
  - name: lint
    contents: |
      Frontend:
      cd frontend && pnpm lint

      Backend:
      cd backend && uv run ruff check .

      Auto-fix:
      cd frontend && pnpm lint --fix
      cd backend && uv run ruff check --fix .

  - name: test
    contents: |
      Frontend unit tests:
      cd frontend && pnpm test

      Backend unit tests:
      cd backend && uv run pytest

      E2E tests (requires dev server running):
      cd frontend && pnpm test:e2e

  - name: build
    contents: |
      Frontend:
      cd frontend && pnpm build

      Backend:
      cd backend && uv run python -m build

  - name: dev-server
    contents: |
      Start the full development stack:
      cd backend && uv run uvicorn main:app --reload &
      cd frontend && pnpm dev

      Frontend: http://localhost:3000
      Backend API: http://localhost:8000
      API docs: http://localhost:8000/docs

  - name: database
    contents: |
      Run migrations:
      cd backend && uv run alembic upgrade head

      Create a new migration:
      cd backend && uv run alembic revision --autogenerate -m "description"

      Reset the database:
      cd backend && uv run alembic downgrade base && uv run alembic upgrade head

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Überblick

initialize

Einfache Form

Strukturierte Form

Wann `initialize` statt `maintenance` verwenden

maintenance

knowledge

Schritttypen

Shell-Befehle (`run`)

GitHub Actions (`uses`)

`run` vs. `uses`: wann Sie was verwenden sollten

Umgebungsvariablen und Secrets

Umgebungsvariablen pro Schritt

Schrittübergreifende Umgebungsvariablen (`$ENVRC`)

Secrets

Dateianhänge

Git-basierte Blueprints

Vollständiges Beispiel

Organisationsweites Blueprint

Blueprint auf Repo-Ebene

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Documentation Index

​Überblick

​initialize

​Einfache Form

​Strukturierte Form

​Wann initialize statt maintenance verwenden

​maintenance

​knowledge

​Schritttypen

​Shell-Befehle (run)

​GitHub Actions (uses)

​run vs. uses: wann Sie was verwenden sollten

​Umgebungsvariablen und Secrets

​Umgebungsvariablen pro Schritt

​Schrittübergreifende Umgebungsvariablen ($ENVRC)

​Secrets

​Dateianhänge

​Git-basierte Blueprints

​Vollständiges Beispiel

​Organisationsweites Blueprint

​Blueprint auf Repo-Ebene

Überblick

initialize

Einfache Form

Strukturierte Form

Wann `initialize` statt `maintenance` verwenden

maintenance

knowledge

Schritttypen

Shell-Befehle (`run`)

GitHub Actions (`uses`)

`run` vs. `uses`: wann Sie was verwenden sollten

Umgebungsvariablen und Secrets

Umgebungsvariablen pro Schritt

Schrittübergreifende Umgebungsvariablen (`$ENVRC`)

Secrets

Dateianhänge

Git-basierte Blueprints

Vollständiges Beispiel

Organisationsweites Blueprint

Blueprint auf Repo-Ebene