Skip to main content
Devin kann in deinen Databricks-Workspaces als asynchroner Kollege arbeiten: Kataloge erkunden, fehlgeschlagene Jobs debuggen, SQL optimieren, Notebooks schreiben und testen sowie Änderungen über deinen gewohnten Git-Workflow ausliefern. Diese Anleitung zeigt Schritt für Schritt, wie du das mit einem dedizierten Databricks-Service-Principal einrichtest, als der sich Devin authentifiziert und der über Unity Catalog verwaltet wird.
Die Integration besteht aus drei Bausteinen, die du bereits selbst kontrollierst: einem Databricks-Service-Principal, der Databricks CLI, die über einen Environment-Blueprint installiert wird, und (optional) dem Databricks Skills Plugin. Databricks, die Workspaces und sämtliche Berechtigungen bleiben in deinem Account.

Authentifizierungsmethode für Devin wählen

Devin authentifiziert sich bei Databricks auf eine von zwei Arten als Service-Principal. Beide nutzen denselben Service-Principal, die per Blueprint installierte CLI und dieselben Unity-Catalog-Berechtigungen; sie unterscheiden sich lediglich im Credential. Beginne mit Option A, wenn Devin schon heute mit Databricks arbeiten soll. Du kannst später zu Option B wechseln, ohne den Service-Principal oder dessen Berechtigungen anzupassen.

Warum Devin mit Databricks verbinden?

  • Devin arbeitet dort, wo Ihre Datenplattform lebt. Die meiste Arbeit in Databricks besteht nicht nur darin, Notebooks in einem Repo zu bearbeiten. Es geht darum zu prüfen, warum ein Job fehlgeschlagen ist, das Schema einer Tabelle zu lesen, eine Query gegen ein Warehouse auszuführen oder eine Pipeline zu untersuchen. Mit der CLI werden daraus Aufgaben, die Devin selbst erledigen kann, statt Fragen an einen Menschen.
  • Eine einzige prüfbare Identität. Devin agiert als ein von Ihnen erstellter Service-Principal, sodass jeder API call, jede Query und jeder Job-Lauf in den Databricks-Audit-Logs und in der Unity-Catalog-Lineage unter dieser Identität erscheint – und nicht unter dem persönlichen Token eines Entwicklers.
  • Unity Catalog entscheidet, worauf Devin zugreifen darf. OAuth entscheidet, ob Devin sich authentifizieren kann. Unity-Catalog-Grants und Workspace-Berechtigungen entscheiden, was gelesen oder geändert werden darf. Sie können in der Produktion schreibgeschützt starten, Devin einen Sandbox-Catalog zum Entwickeln geben und den Geltungsbereich erst erweitern, wenn Sie gesehen haben, wie Devin sich verhält.
  • Ein Weg ganz ohne gespeichertes Secret. Mit OIDC-Token-Föderation (Option B) speichert Devin zu keinem Zeitpunkt ein Databricks-Token oder ein Client Secret. Jede Sitzung tauscht ein 60 Sekunden gültiges Devin-Identitäts-Token gegen ein kurzlebiges Databricks-OAuth-Token.

Übersicht

Das Setup besteht aus vier Teilen: Das Databricks Skills Plugin ist eine fünfte, optionale Schicht: Es vermittelt Devin zusätzlich zur CLI Databricks-spezifische Workflows (Asset Bundles, Jobs, SQL, Unity Catalog).

Voraussetzungen

Databricks
  • Ein Databricks-Konto auf AWS, Azure oder GCP mit Account-Admin-Zugriff für die Person, die das Setup durchführt. Das Erstellen von Service-Principals, OAuth-Secrets und Federation-Richtlinien erfolgt auf Account-Ebene.
  • Ein oder mehrere Workspaces mit aktiviertem Unity Catalog. Diese Anleitung geht davon aus, dass Unity Catalog die Daten verwaltet, auf die Devin zugreifen soll.
  • Die Databricks CLI auf der Maschine des Admins für die folgenden Befehle auf Account-Ebene. Dafür genügt jede aktuelle Version. Devins eigene Installation erfolgt separat in Schritt 2.
Devin
  • Berechtigung zum Bearbeiten des Environment-Blueprints Ihrer Organisation (Settings > Environment > Blueprints).
  • Für Option A: Berechtigung zum Hinzufügen von Devin Secrets.
  • Für Option B: Ihre Devin-OIDC-Issuer-URL und Organization ID. Schritt 2 zeigt, wie Sie beides aus einem Token innerhalb einer Devin-Sitzung auslesen. Hintergrundinformationen finden Sie unter Cloud Authentication with OIDC.
Netzwerk
  • Devin-Sitzungen müssen Ihren Workspace-Host über HTTPS erreichen können (zum Beispiel https://dbc-xxxx.cloud.databricks.com, https://adb-xxxx.azuredatabricks.net oder https://xxxx.gcp.databricks.com). Wenn Ihre Organisation eine Devin-Netzwerkrichtlinie verwendet, fügen Sie den Workspace-Host hinzu sowie – für Befehle auf Account-Ebene – den Account-Host (accounts.cloud.databricks.com, accounts.azuredatabricks.net oder accounts.gcp.databricks.com).
  • Für Option B muss Databricks Devins JWKS unter https://<your-devin-host>/.well-known/jwks.json über das öffentliche Internet abrufen können, um Token-Signaturen zu verifizieren.

Schritt 1: Service-Principal erstellen

Erstellen Sie einen dedizierten Service-Principal für Devin, anstatt einen bestehenden wiederzuverwenden, von dem andere Automatisierungen abhängen. Ein dedizierter Principal hält Audit-Logs und Berechtigungs-Reviews übersichtlich. Von einer Maschine aus, auf der Sie am Databricks-Account (nicht an einem Workspace) angemeldet sind:
Notieren Sie zwei Werte aus der Ausgabe: Weisen Sie den Service-Principal anschließend jedem Workspace zu, den Devin verwenden soll. Das können Sie in der Account-Konsole unter User management → Service principals oder über die CLI erledigen:
Verwenden Sie USER, nicht ADMIN. Devin benötigt keine Workspace-Adminrechte.

Schritt 2: Devin mit dem Service-Principal verbinden

Wählen Sie eine der beiden folgenden Optionen. Jede ist für sich vollständig: Sie installiert die Databricks CLI über ein Blueprint unter Settings > Environment > Blueprints und konfiguriert die CLI so, dass sie sich als der Service-Principal aus Schritt 1 authentifiziert.
  • Option A: OAuth Client Secret. Standardmäßiges OAuth M2M: Der Service-Principal erhält ein Client Secret, das Sie in Devin Secrets hinterlegen. Der schnellste Einstieg.
  • Option B: OIDC-Token-Föderation. Jede Devin-Sitzung kann ein kurzlebiges, von Devin signiertes OpenID-Connect-Token ausstellen. Die Token-Föderation von Databricks ermöglicht es dem Service-Principal, diesem Issuer zu vertrauen, sodass Devin sein eigenes Identitätstoken gegen ein Databricks-OAuth-Token eintauscht. Dabei wird nie ein Databricks Secret erstellt oder gespeichert – deshalb empfiehlt Databricks diese Variante ausdrücklich für automatisierte Workloads.
Persönliche Zugriffstoken (PATs), die an einen menschlichen Nutzer gebunden sind, werden für keine der beiden Optionen empfohlen. Sie umgehen den Service-Principal, laufen unvorhersehbar ab und schreiben Devins Aktionen einer Person zu.

Option A: OAuth Client Secret

Sie möchten überhaupt kein Databricks-Secret verwalten? Dann springen Sie direkt zu Option B: OIDC-Token-Föderation. Sie können aber auch hier starten und später wechseln: Ersetzen Sie den Blueprint durch den aus Option B, erstellen Sie die Föderationsrichtlinie und löschen Sie anschließend das OAuth-Secret sowie das Devin Secret DATABRICKS_CLIENT_SECRET.

1. Ein OAuth-Secret generieren

Öffnen Sie in der Account-Konsole den Service-Principal aus Schritt 1 und generieren Sie ein OAuth-Secret. Legen Sie die kürzeste Lebensdauer fest, die Ihr Rotationsprozess unterstützt (maximal 730 Tage), und beschränken Sie das Secret auf die von Devin benötigten API-Geltungsbereiche, etwa sql, jobs und unity-catalog. Wählen Sie nicht alle Geltungsbereiche aus.

2. Die Devin Secrets hinzufügen

Fügen Sie in Devin die folgenden Werte als Devin Secrets im Tab Secrets des Blueprints hinzu, den Sie als Nächstes bearbeiten (Organisation oder Repository): Die CLI wählt OAuth M2M automatisch, sobald eine Client ID und ein Client Secret vorhanden sind; DATABRICKS_AUTH_TYPE ist daher nicht erforderlich. Setzen Sie den Wert nur dann auf oauth-m2m, wenn Sie alle anderen Methoden explizit ausschließen möchten. Secrets werden zu Beginn jeder neuen Sitzung als Umgebungsvariablen bereitgestellt, sodass die CLI keine Profildatei benötigt. Ein rotiertes Secret greift ohne Rebuild ab der nächsten neuen Sitzung.

3. Blueprint hinzufügen

Installiert nur die CLI. Die Authentifizierung erfolgt vollständig über die drei oben genannten Secrets.
Schreiben Sie die Secrets während initialize nicht in eine Datei; alles, was dort geschrieben wird, landet fest im Snapshot.
Setzen Sie zusätzlich nicht DATABRICKS_TOKEN und belassen Sie kein ~/.databrickscfg-Profil im Snapshot. Widersprüchliche Anmeldedaten sind die häufigste Ursache dafür, dass die M2M-Authentifizierung fehlschlägt.

4. Snapshot erstellen

Speichern Sie den Blueprint und warten Sie, bis der Build Success anzeigt. Starten Sie anschließend eine neue Sitzung. Bestehende Sitzungen behalten den alten Snapshot. Fahren Sie mit Schritt 3 fort.

Option B: OIDC-Token-Föderation

Devin-Sitzungen erzeugen kurzlebige Identitätstoken (iss, sub, aud), und eine Föderationsrichtlinie am Service-Principal weist Databricks an, diesen zu vertrauen. Der Blueprint installiert die devin-oidc-CLI, kapselt databricks so, dass jeder Aufruf ein frisches Token mitführt, und legt ein Profil an, das auf Ihren Service-Principal verweist. Anschließend lesen Sie die Claims des Tokens aus einer Sitzung aus und erstellen eine passende Richtlinie.
Sie möchten zuerst den kürzesten Weg gehen? Beginnen Sie mit Option A und kehren Sie hierher zurück, sobald Sie das gespeicherte Secret ablösen möchten.

1. Blueprint hinzufügen

Zwei Platzhalter im Profil müssen durch eigene Werte ersetzt werden:
Das Profil enthält kein Secret und kann daher gefahrlos während initialize geschrieben werden. Wenn Sie von Option A wechseln, entfernen Sie das Devin Secret DATABRICKS_CLIENT_SECRET, sobald die untenstehende Richtlinie eingerichtet ist, damit die CLI nicht zwei Anmeldedaten vorfindet.

2. Snapshot erstellen

Speichern Sie den Blueprint und warten Sie, bis der Build den Status Success anzeigt. Nichts im Blueprint hängt von der Föderationsrichtlinie ab, die Sie als Nächstes erstellen – ein erneuter Build ist danach also nicht nötig.

3. Die Föderationsrichtlinie erstellen

Sobald der Blueprint erstellt ist, können Devin-Sitzungen Identitätstoken ausstellen. Verwenden Sie eines davon, um die genauen Claims auszulesen, denen Databricks vertrauen muss, und erstellen Sie anschließend eine passende Föderationsrichtlinie für den Service-Principal.
1

Issuer und Subject auslesen

Starten Sie eine neue Devin-Sitzung und lassen Sie Folgendes ausführen. Ausgegeben werden ausschließlich die Identitäts-Claims des Tokens, niemals das Token selbst.
Erwartete Form:
Bei Enterprise-Deployments ist iss Ihre eigene Devin-URL (zum Beispiel https://yourcompany.devinenterprise.com). Übernehmen Sie iss und sub exakt so, wie sie ausgegeben werden. Fügen Sie das rohe Token nicht in Tickets oder Dokumente ein; es ist für die nächsten 60 Sekunden ein gültiges Bearer-Credential.
2

Die Föderationsrichtlinie schreiben

Speichern Sie Folgendes als devin-federation-policy.json und setzen Sie dabei die Werte aus dem vorherigen Schritt ein:
Alle drei Felder werden exakt abgeglichen:
  • issuer muss dem iss des Tokens entsprechen, einschließlich Schema und ohne abschließenden Schrägstrich.
  • audiences muss die Audience enthalten, die Devin anfordert (in dieser Anleitung databricks).
  • subject muss dem sub des Tokens entsprechen. Standardmäßig ist das Subject Ihre Organisations-ID, sodass sich jede Sitzung der Organisation als dieser Principal authentifizieren kann. Für Databricks ist das die richtige Granularität, da Föderationsrichtlinien das Subject als wörtliche Zeichenkette abgleichen. Sitzungsbezogene Claims wie devin_id ändern sich bei jeder Sitzung und lassen sich mit einer statischen Richtlinie nicht abgleichen.
Lassen Sie subject_claim, jwks_uri und jwks_json leer. Databricks verwendet standardmäßig den sub-Claim und ermittelt die JWKS über /.well-known/openid-configuration des Issuers.
3

Die Richtlinie an den Service-Principal anhängen

Prüfen Sie, ob sie vorhanden ist:
Das vom Blueprint geschriebene Profil verweist bereits auf diesen Service-Principal, ein erneutes Erstellen ist daher nicht nötig. Fahren Sie mit Schritt 3 fort.

Rebuilds und Versions-Pinning

Sowohl das Databricks-Installationsskript als auch setup-devin-oidc@main folgen ihren Upstream-main-Branches, sodass ein vollständiger Build neue Releases übernimmt; ein differenzieller Build überspringt initialize und behält die bereits im Snapshot vorhandenen Versionen bei, bis sich der Blueprint ändert. Wenn Sie reproduzierbare Builds benötigen, laden Sie den Installer nicht von main, sondern von einem Release-Tag (zum Beispiel .../databricks/setup-cli/v1.17.0/install.sh) – damit wird genau diese CLI-Version installiert – und pinnen Sie die Action an einen Commit-SHA an (setup-devin-oidc@<sha>).

Schritt 3: Berechtigungen erteilen

Die Authentifizierung belegt lediglich, wer Devin ist. Was Devin sehen oder ändern darf, legen die Workspace-Berechtigungen und die Unity-Catalog-Grants fest, die Sie jederzeit anpassen können, ohne den Blueprint zu ändern. Beginnen Sie mit dem kleinsten Profil, das für die Aufgabe ausreicht, und erweitern Sie es gezielt.

Berechtigungsprofile

Grant-Statements adressieren den Service-Principal über seine Application-ID:
Wenn Sie eine gruppenbasierte Verwaltung bevorzugen, fügen Sie den Service-Principal einer Gruppe wie devin-agents hinzu und erteilen Sie die Berechtigungen stattdessen der Gruppe.
Codeänderungen sollten weiterhin über Pull-Requests laufen. Devin kann Produktionsdaten lesen, um ein Problem zu verstehen und einen Fix in der Sandbox zu validieren, aber die Änderung am Notebook, an der Job-Definition oder am Asset Bundle gelangt über Ihren normalen Review-Prozess in die Produktion – nicht durch direktes Bearbeiten der Produktionsumgebung.

Step 4: Databricks Skills Plugin installieren (optional)

Databricks veröffentlicht Agent Skills, die Coding-Agents Databricks-Workflows vermitteln: Asset Bundles, Jobs, SQL, Unity Catalog und Spark. Installierst du sie als Devin-Plugin, verfügt Devin zusätzlich zur CLI über dieses Know-how.
  1. Öffne Customize → Plugins und wähle Add plugin → From repository.
  2. Gib das Repository databricks/databricks-agent-skills und das Unterverzeichnis plugins/databricks/claude an. Das Plugin-Manifest liegt in diesem Unterordner – bei einer Installation aus dem Root-Verzeichnis erscheint daher die Meldung No plugin manifest found.
  3. Installiere im Geltungsbereich Organization, falls du in Step 2 ein Organization Blueprint verwendet hast. Hast du ein Repository Blueprint verwendet, deklariere das Plugin stattdessen in der .devin/config.json des jeweiligen Repositorys (siehe Vererbung und Ebenen), damit nur Sitzungen mit der CLI auch die Skills erhalten.
  4. Pinne das Plugin an einen Commit an, sobald es funktioniert, damit Änderungen aus dem Upstream nicht ungeprüft in deinen Sitzungen landen.
Die Kern-Skill des Plugins empfiehlt, databricks auth login auszuführen, um ein Profil einzurichten. Dieser interaktive Browser-Ablauf lässt sich in einer unbeaufsichtigten Devin-Sitzung nicht abschließen und ist hier auch nicht nötig: Der knowledge-Eintrag aus Step 2 teilt Devin mit, dass die CLI bereits authentifiziert ist.

Schritt 5: Überprüfen

Starten Sie eine neue Sitzung (nachdem der Blueprint-Build erfolgreich abgeschlossen wurde) und bitten Sie Devin, Folgendes auszuführen:
current-user me sollte den Service-Principal zurückgeben, wobei userName seiner Anwendungs-ID entspricht. So prüfen Sie, welche Authentifizierungsmethode die CLI gewählt hat:
Bei Option A wird hier oauth-m2m gemeldet, bei Option B env-oidc. Eine erfolgreiche Authentifizierung bedeutet nicht, dass Devin auch auf Ihre Daten zugreifen kann. Stellen Sie sicher, dass die Berechtigungen aus Schritt 3 greifen:
Ersetze <catalog-name> durch einen Katalog, den du in Schritt 3 freigegeben hast (die Beispiele dort verwenden analytics). Bitte Devin anschließend, eine kleine schreibgeschützte Abfrage auf einem Warehouse auszuführen, für das Devin CAN USE hat, und – falls du ein Build-Profil eingerichtet hast – eine Tabelle in devin_dev zu erstellen und wieder zu löschen. Eine Abfrage auf eine Produktionstabelle, für die Devin kein SELECT hat, sollte fehlschlagen; genau dieser Fehler zeigt, dass die Berechtigungsgrenze greift.

Fehlerbehebung

Support

Für das Setup auf Databricks-Seite (Service-Principals, OAuth-Secrets, Föderationsrichtlinien, Unity Catalog) siehe die Databricks-Dokumentation zur Authentifizierung (bei Bedarf zur Azure- oder GCP-Ausgabe wechseln). Für das Setup auf Devin-Seite (Blueprints, OIDC, Plugins, Netzwerkrichtlinie) wende dich an support@cognition.ai oder an dein Account-Team.