Veröffentlicht am: 27. Oktober 2026

12 Minuten Lesezeit

GitLab Duo Agent Platform in Geschäftssysteme einbinden

Ein eigener GitLab-Flow, aufgerufen aus Salesforce: So kommt jeder Fehler als GitLab-Issue mit Ursachenanalyse an, bereit zur Behebung und zum Deployment.

Entwickler(innen) nutzen GitLab Duo Agent Platform meist dort, wo sie ohnehin arbeiten: in der IDE, in Merge Requests und in Issues. DevSecOps-Teams betreuen aber auch die Geschäftssysteme, auf die sich der Rest des Unternehmens stützt, und auch dort treten Fehler auf.

In Salesforce zum Beispiel wird ein Fehler protokolliert, wenn eine Validierung fehlschlägt, ein Callout in einen Timeout läuft oder ein Nullwert durch einen Trigger rutscht. Das Log erklärt aber nicht die Ursache. Jemand aus dem Engineering muss trotzdem den Stack Trace lesen, die Klasse im Repository finden, prüfen, was sich zuletzt geändert hat, und entscheiden, ob es sich um einen Einzelfall oder eine Regression handelt. Die Person aus dem Fachbereich, bei der der Fehler aufgetreten ist, muss so lange warten.

Liegen deine Salesforce-Metadaten in GitLab und laufen ihre Deployments über GitLab CI/CD, ist der Code, der den Fehler erklärt, bereits vorhanden. In diesem Tutorial ruft Salesforce über die Flows API einen eigenen Flow in GitLab Duo Agent Platform auf, sobald ein Fehler auftritt. Der Flow untersucht den Code, und dein Team erhält ein GitLab-Issue, das die Ursachenanalyse bereits enthält.

Dabei arbeiten drei Teile der GitLab-Plattform zusammen: GitLab Duo Agent Platform untersucht den Fehler, ein GitLab-Issue verfolgt die Arbeit, und GitLab CI/CD führt den Flow aus und bringt die Korrektur in Produktion.

Salesforce ist das Beispiel, das wir in diesem Tutorial durchspielen. Derselbe Ansatz funktioniert aber mit jedem System, das eine HTTP-Anfrage senden kann.

Überblick

Salesforce ruft GitLab ein einziges Mal auf. Den Rest übernimmt ein eigener Flow in GitLab Duo Agent Platform.

Vom Salesforce-Fehler zur ausgelieferten Korrektur auf einer Plattform

Fehler erreichen GitLab Duo Agent Platform automatisch aus deiner Fehlerbehandlung in Apex oder auf Wunsch über einen Button. In beiden Fällen ruft derselbe Apex-Job die Flows API auf, und der Flow legt ein Issue mit seiner Analyse an.

Voraussetzungen

  • GitLab Premium oder Ultimate, auf GitLab.com oder ab GitLab 19.5. Die in diesem Tutorial genutzte Flows API ist ab 19.5 allgemein verfügbar.
  • GitLab Duo Agent Platform ist aktiviert, und Custom Flows sind für deine Top-Level-Gruppe erlaubt.
  • Deine Salesforce-Metadaten (Apex-Klassen, Trigger, Flows) liegen in einem GitLab-Projekt. Dieses Projekt liest der Flow.
  • Du hast in diesem Projekt die Rolle Maintainer oder Owner.
  • In Salesforce hast du die Berechtigung, eine Named Credential, einen benutzerdefinierten Metadatentyp und Apex-Klassen anzulegen.
  • Deine Salesforce-Deployments laufen über eine GitLab-CI/CD-Pipeline, damit die Korrektur aus demselben Issue heraus ausgeliefert werden kann.

1. Schritt: Triage-Flow schreiben

Beginne in GitLab, denn Salesforce braucht später die ID des Flows.

Ein Custom Flow ist eine einzige YAML-Datei in der Syntax der Flow Registry v1. Dieser Flow hat einen einzigen Agenten. Wenn Salesforce den Flow startet, übergibt es die Fehlerdetails als Ziel des Flows. Der Agent liest sie als context:goal, untersucht das Repository und legt ein Issue an.

      version: "v1"
environment: ambient

components:
  - name: "sf_error_triage"
    type: AgentComponent
    prompt_id: "sf_error_triage_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "error_report"
    toolset:
      - "find_files"      # locate the class or Flow in the repository
      - "grep"
      - "read_file"
      - "list_commits"    # find recent changes to that file
      - "create_issue"    # the only write: open the triage issue

prompts:
  - prompt_id: "sf_error_triage_prompt"
    prompt_template:
      system: |
        You triage Salesforce runtime errors for a team that keeps its
        Salesforce metadata (Apex classes, triggers, Flows) in this project.

        You receive an error report with a class name, exception type,
        message and stack trace.

        1. Find the source file for the class or Flow named in the report.
        2. Read the code around the lines in the stack trace.
        3. List recent commits that touched that file and identify any change
           that plausibly introduced the error.
        4. Create one issue:
           - Title: "[Salesforce error] <exception type> in <class>"
           - Label: salesforce-error
           - Description: the original error, then sections for
             Likely cause, Affected component, Suspect change,
             Suggested next step, and Confidence (high, medium or low,
             with one line of reasoning).

        Rules:
        - Cite file paths, line numbers and commit SHAs for every claim.
        - If you cannot find the code or a suspect commit, say so. Do not guess.
        - Do not change code. A person decides what happens next.
      user: |
        Project ID: {{project_id}}
        Error report:
        {{error_report}}
      placeholder: history

routers:
  - from: "sf_error_triage"
    to: "end"

flow:
  entry_point: "sf_error_triage"

    

Die Tool-Auswahl ist bewusst knapp gehalten: Vier Tools lesen, eines legt ein Issue an. Der Flow kann keinen Code pushen und keine bestehenden Issues ändern. So lässt er sich leicht prüfen, und es fällt leicht, ihm zu vertrauen.

Zwei Zeilen im Prompt sind dabei entscheidend. Die Pflicht zu einer Quellenangabe für jede Aussage erlaubt es Engineers, die Argumentation in einer Minute zu prüfen. Die Erlaubnis, "nicht gefunden" zu melden, hält den Agenten davon ab, eine Ursache zu erfinden.

Um den Flow anzulegen, öffne dein Projekt, wähle AI > Flows > New flow und dann Flow aus, füge das YAML ein und wähle Create flow aus. Du kannst den Flow auch in VS Code mit dem GitLab Flow Builder erstellen und testen.

2. Schritt: Flow aktivieren und Consumer-ID ermitteln

Ein Flow muss in einem Projekt aktiviert sein, bevor er ausgeführt werden kann.

  1. Wähle in deinem Projekt AI > Flows aus, öffne den Tab Managed und wähle deinen Flow aus.
  2. Wähle Enable und dann das Projekt mit deinem Salesforce-Code aus. GitLab legt für den Flow ein Dienstkonto namens ai-<flow>-<group> an. Der Flow läuft mit einer Composite Identity und kann deshalb nie auf mehr zugreifen als die Person, die ihn startet. Startet Salesforce den Flow über die API, führt GitLab ihn als dieses Dienstkonto aus.
  3. Einen Trigger für Erwähnungen oder Zuweisungen brauchst du nicht. Salesforce startet diesen Flow über die API.

Um einen Custom Flow über die API zu starten, übergibt Salesforce die ai_catalog_item_consumer_id des Flows. Ermittle sie mit einer kurzen GraphQL-Abfrage aus der Dokumentation und verwende die Zahl am Ende des zurückgegebenen Werts gid://gitlab/AiCatalogItemConsumer/<number>. Notiere sie zusammen mit der Projekt-ID.

Lege abschließend ein Project Access Token mit dem Scope api und mindestens der Rolle Developer an. Salesforce nutzt es, um GitLab aufzurufen. Mit einer niedrigeren Rolle verweigert die API das Ausführen von Katalog-Flows.

3. Schritt: Flow aus Salesforce aufrufen

Das Token in einer Named Credential speichern: Lege eine Named Credential namens GitLab_API mit der URL https://gitlab.com an. Hinterlege dafür eine External Credential, die dein Project Access Token im Header PRIVATE-TOKEN sendet. Das Token taucht so nie im Code auf.

Die Flows API aus einem Queueable aufrufen: Salesforce erlaubt keine Callouts mitten im Speichern eines Datensatzes, deshalb läuft der Aufruf als Hintergrundjob. Der Job wandelt die Exception in das Ziel des Flows um und startet den Flow:

      public with sharing class DuoTriageJob implements Queueable, Database.AllowsCallouts {
    private final String goal;

    public DuoTriageJob(Exception e, String className) {
        goal = 'Class: ' + className
            + '\nException: ' + e.getTypeName()
            + '\nMessage: ' + e.getMessage()
            + '\nStack trace:\n' + e.getStackTraceString();
    }

    public void execute(QueueableContext ctx) {
        Duo_Triage_Setting__mdt cfg = Duo_Triage_Setting__mdt.getInstance('Default');

        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:GitLab_API/api/v4/ai/duo_workflows/workflows');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(new Map<String, Object>{
            'project_id'                    => cfg.Project_Id__c,
            'ai_catalog_item_consumer_id'   => cfg.Consumer_Id__c.intValue(),
            'goal'                          => goal,
            'start_workflow'                => true,
            'allow_agent_to_request_user'   => false,
            'agent_privileges'              => new List<Integer>{ 1, 2, 3 },
            'pre_approved_agent_privileges' => new List<Integer>{ 1, 2, 3 }
        }));
        HttpResponse res = new Http().send(req);
        // 201 Created: the response includes web_url, a link to the agent session.
    }
}

    

Die Projekt-ID und die Consumer-ID aus dem 2. Schritt liegen in einem benutzerdefinierten Metadatentyp, Duo_Triage_Setting__mdt. So lassen sie sich ohne Deployment ändern.

Drei Einstellungen im Request-Body sind besonders wichtig:

  • allow_agent_to_request_user: false bedeutet, dass der Flow bis zum Ende läuft, ohne für Rückfragen anzuhalten. Um 2 Uhr nachts schaut niemand auf einen Salesforce-Fehler.
  • agent_privileges beschränkt den Agenten auf das Lesen von Dateien (1), das Lesen in GitLab (2) und das Schreiben in GitLab (3), das er zum Anlegen des Issues braucht. Befehle ausführen oder Git nutzen kann er nicht. Lass dir alle Privilegien auflisten, um die IDs auf deiner Instanz zu prüfen.
  • pre_approved_agent_privileges wiederholt dieselbe Liste, damit der Flow nie anhält, um auf eine Freigabe für Tools zu warten.

Dieses Beispiel verzichtet auf Prüfungen der Antwort, Wiederholungsversuche und Tests. Ergänze sie, bevor du in Produktion gehst.

4. Schritt: Flow automatisch oder auf Wunsch starten

Automatisch: Stelle den Job überall dort in die Warteschlange, wo dein Code eine Exception abfängt und behandelt:

      try {
    OpportunityDiscountService.applyTierDiscount(opportunities);
} catch (Exception e) {
    System.enqueueJob(new DuoTriageJob(e, 'OpportunityDiscountService'));
    // ...your existing error handling
}

    

Wird die gesamte Transaktion zurückgerollt, verwirft Salesforce auch den eingereihten Job. Setze den Aufruf deshalb dort, wo dein Code den Fehler behandelt und weiterläuft.

Auf Wunsch: Manche Teams entscheiden lieber selbst, welche Fehler eine Untersuchung wert sind. Verpacke den Job in eine aufrufbare Apex-Aktion, beschrifte sie mit Ask GitLab Duo to investigate und füge sie einem Bildschirm-Flow hinzu, der als Schnellaktion auf dem Datensatz läuft, in dem du Fehler festhältst, etwa einem Log-Datensatz oder einem Support-Fall. Ein Klick in Salesforce, und einige Minuten später erscheint das Issue in GitLab.

5. Schritt: Ergebnis prüfen

Eine Person speichert eine Opportunity, ein Apex-Trigger löst eine Exception aus, und einige Minuten später erscheint ein neues Issue im GitLab-Projekt. Hier ein Beispiel dafür, was der Flow schreibt:

      ## [Salesforce error] System.NullPointerException in OpportunityDiscountService

Label: salesforce-error

### Original error
Attempt to de-reference a null object
Class.OpportunityDiscountService.applyTierDiscount: line 48, column 1
Trigger.OpportunityTrigger: line 12, column 1

### Likely cause
applyTierDiscount() reads opp.Account.Tier__c without a null check (line 48).
Opportunities saved without an Account reach this line with opp.Account == null.

### Affected component
force-app/main/default/classes/OpportunityDiscountService.cls,
called from OpportunityTrigger (before update).

### Suspect change
Commit 3f9c2ab, "Apply tier discount on stage change", added the Tier__c lookup.
Before that commit, the method returned early when AccountId was blank.

### Suggested next step
Restore the early return for a blank AccountId, or guard the lookup.
Add a test that updates an Opportunity with no Account.

### Confidence
High. The stack trace line matches the new code in 3f9c2ab.

    

Weder in Salesforce noch in der Codebasis hat sich etwas geändert. Der Flow hat die erste Untersuchungsrunde übernommen und die Entscheidung einem Engineer überlassen: sofort beheben, einplanen oder als erwartetes Verhalten schließen.

Die Antwort der Flows API enthält eine web_url für die Agenten-Session. Öffne sie, um jeden Schritt des Flows nachzuvollziehen. So lässt sich der Prompt am besten feinjustieren.

Leitplanken für die Produktion einziehen

Prüfe diese Punkte, bevor du das Setup in Produktion nimmst. Von ihnen hängt ab, ob das Muster unter echtem Datenverkehr trägt.

  • Nur die Struktur des Fehlers senden: Entferne Datensatz-IDs, E-Mail-Adressen und Freitext, der Kundendaten enthalten kann, aus der Meldung, bevor sie Salesforce verlässt. Prüfe gemeinsam mit deinem Security-Team, was das Ziel enthält, bevor du das Setup aktivierst.
  • So wenige Privilegien wie möglich vergeben: Dateien lesen, in GitLab lesen und ein Issue anlegen reicht aus. Erweitere den Flow, etwa um Merge Requests zu öffnen, erst dann, wenn er sich mit präzisen Analysen Vertrauen verdient hat.
  • Das Token eingrenzen: Verwende ein Project Access Token für ein einziges Projekt, kein persönliches Token, und rotiere es nach Plan.
  • Einen Menschen verantwortlich lassen: Der Flow untersucht, ein Engineer entscheidet. Die Quellenangaben in jedem Issue erlauben es, die Argumentation zu überprüfen, statt sie neu zu erarbeiten.

Fehler bis zur Korrektur auf einer Plattform verfolgen

So sieht der Weg dieses Fehlers von Anfang bis Ende aus:

  • GitLab Duo untersucht ihn: Der Flow liest den Stack Trace, findet den Code und verweist auf die Änderung, die den Fehler am wahrscheinlichsten verursacht hat.
  • Ein GitLab-Issue verfolgt ihn: Die Analyse wird zu Arbeit, die das Team wie jedes andere Issue mit Labels versehen, priorisieren, zuweisen und in einen Meilenstein einplanen kann.
  • GitLab CI/CD führt den Flow aus und bringt die Korrektur in Produktion: Der Flow selbst läuft auf GitLab CI/CD, ebenso deine Deployment-Pipeline für Salesforce. Ein Engineer öffnet aus dem Issue einen Merge Request, die Pipeline validiert die Änderung und deployt sie nach Salesforce, und das Issue wird geschlossen, sobald der Merge Request gemergt ist.

Weil jeder Schritt in GitLab stattfindet, bleibt die Spur durchgängig. Das Issue verweist auf den Merge Request, der Merge Request auf seine Pipeline und die Pipeline auf das Deployment. So ist für alle nachvollziehbar, was kaputtgegangen ist, warum, wer es behoben hat und wann die Korrektur in Produktion ging.

Muster auf andere Systeme übertragen

Ohne die Salesforce-Details ist das Muster einfach: Ein Geschäftssystem sendet einen einzigen HTTP-Aufruf, und ein eigener Flow in GitLab Duo, der deinen Code kennt, übernimmt die Untersuchung. Jedes System, das eine Anfrage senden kann, kann einen Flow starten.

Einige Ideen, wo dasselbe Muster helfen könnte:

  • Eine fehlgeschlagene Synchronisierung in einer ERP-Integration, zurückverfolgt bis zum zuletzt geänderten Mapping-Code.
  • Ein Support-Fall mit dem Tag "möglicher Bug", der mit den letzten Releases abgeglichen wird, bevor er bei einem Engineer landet.
  • Ein fehlgeschlagener geplanter Datenjob, zugeordnet zur letzten Änderung in seiner Pipeline-Definition.

Für DevSecOps-Teams heißt das: Fehler aus den betreuten Geschäftssystemen kommen als Issues mit einer wahrscheinlichen Ursache an und nicht als rohe Logs, die von Hand nachverfolgt werden müssen. Fachbereiche müssen GitLab nicht lernen, und das Engineering muss kein weiteres Dashboard im Blick behalten. Jedes System macht weiter seine Arbeit, und GitLab Duo Agent Platform verschafft dem Engineering bei jedem Fehler einen Vorsprung.

Selbst ausprobieren

Such dir ein Geschäftssystem aus, das dein Team betreut, und einen Fehler, den es heute protokolliert. Gib einem Custom Flow den Code, ruf ihn aus diesem System auf und sieh dir an, was die erste Analyse ergibt. Starte eine kostenlose Testversion von GitLab Duo Agent Platform, oder, wenn du bereits GitLab Premium oder Ultimate nutzt, aktiviere Duo Agent Platform und baue deinen ersten Custom Flow.

Weiterführende Informationen

Feedback erwünscht

Hat dir dieser Blogbeitrag gefallen? Hast du Fragen oder Feedback? Erstelle ein neues Diskussionsthema im GitLab-Community-Forum und lass andere an deinen Eindrücken teilhaben.

Feedback teilen

Beginne noch heute, schneller zu entwickeln

Entdecke, was dein Team mit der intelligenten Orchestrierungsplattform für DevSecOps erreichen kann.