Kurze Antwort: Um fehlschlagende CI-Builds mit einem KI-Agenten zu beheben, senden Sie das CI-Fehlerereignis an einen Webhook. Ein Coding-Agent prüft dann, ob er den Fehler beheben kann, reproduziert ihn lokal in einem sauberen Worktree und pusht einen Fix auf einen Branch als Draft-Pull-Request. Anschließend prüft und mergt ein Mensch. Keine lokale Reproduktion bedeutet: kein Push.
Ein roter Build um 16 Uhr kostet mehr als der eigentliche Fix. Jemand muss seine aktuelle Arbeit unterbrechen, das Log öffnen, an 900 Zeilen Setup-Ausgabe vorbeiscrollen und findet schließlich einen Linting-Fehler oder einen veralteten Snapshot. Die Behebung dauert zwei Minuten – der Kontextwechsel zwanzig.
Genau an dieser Stelle zahlt sich ein Coding-Agent aus. Wahrscheinlich nutzen Sie bereits Claude Code, Codex oder einen anderen Agenten auf Ihrem Rechner. Was bisher fehlt, ist die Verbindung: ein Mechanismus, der den Fehler bemerkt, ihn mit dem passenden Kontext an den Agenten übergibt und verhindert, dass der Agent bloße Vermutungen in Ihr Repository pusht. Diese Anleitung zeigt, wie Sie diesen Ablauf mit GitHub Actions und einer Sharkly-Automation einrichten – das gleiche Prinzip funktioniert mit jedem CI-System, das HTTP-Requests senden kann.
Was ein KI-Agent in der CI gut reparieren kann (und was nicht)
Ein Agent eignet sich am besten für Fehler, die sich lokal auf einem Laptop reproduzieren lassen und für die es eine kleine, überprüfbare Lösung gibt. Am schlechtesten schneidet er bei Problemen ab, die in der Infrastruktur, bei Zugangsdaten oder bei Drittanbieter-Diensten liegen. Sortieren Sie also vor, bevor Sie automatisieren:
| Fehlertyp | Agenten-Eignung | Warum |
|---|---|---|
| Lint- und Formatierungsfehler | Sehr gut | Deterministisch; der Linter bestätigt die Behebung |
| Typfehler | Sehr gut | Der Compiler bestätigt die Behebung |
| Fehlgeschlagener Snapshot nach beabsichtigter UI-Änderung | Gut | Leicht zu reproduzieren, aber ein Mensch sollte bestätigen, dass die Änderung gewollt war |
| Flaky Test | Gemischt | Reproduktion erfordert wiederholte Durchläufe; die Ursache ist oft eine echte Race Condition |
| Fehlschlagender Unit-Test nach Logikänderung | Gemischt | Möglicherweise ist der Test korrekt und der Code fehlerhaft |
| Runner ohne Speicherplatz, Netzwerk-Timeouts | Schlecht | Im Repository gibt es nichts zu beheben |
| Fehlende oder abgelaufene Secrets, Berechtigungsfehler | Niemals | Der Agent darf keine Zugangsdaten anfassen |
Die Regel, die sich aus dieser Tabelle ergibt: Der Agent liefert nur dann einen Fix, wenn er auf seinem eigenen Computer miterlebt hat, wie der Test erst rot und dann grün wurde. In einem Design-Essay, den das DeepSeek-Harness-Team auf X veröffentlicht hat, wird dieses Muster als „silently reproduce and fix“ bezeichnet: Ein Trigger überwacht Ereignisse, verhält sich standardmäßig ruhig und meldet sich nur mit einem bestätigten, einfachen Fix. Dieser Essay beschreibt den Entwurf eines Prototyps, kein fertiges Produkt, aber das Prinzip gilt für jedes Setup, das Sie selbst aufbauen.
So funktioniert der CI-Fix-Loop
Die Schleife besteht aus fünf Teilen: einem Fehlerereignis, einem signierten Webhook, einem ressourcenschonenden Vorfilter, einer isolierten Reproduktion und einem menschlichen Review-Gate.
- Ihre CI schließt einen Durchlauf mit einem Fehler ab.
- Ein schlanker Workflow sendet einen signierten JSON-Payload an eine Webhook-URL.
- Der Agent liest den Payload und verwirft alles, was nicht in seinen Zuständigkeitsbereich fällt – etwa das falsche Repository oder Fehler auf einem Release-Branch.
- Der Agent erstellt einen Task, checkt einen frischen Worktree aus, reproduziert den Fehler und behebt ihn.
- Er pusht einen Branch und öffnet einen Draft-Pull-Request. Ein Mensch mergt oder schließt ihn.
Die Schritte 3 und 4 laufen als Sharkly-Automation. Eine Automation ist eine gespeicherte Reihe von Anweisungen zusammen mit dem Agent oder Crew, der sie ausführt – ausgelöst durch einen Trigger: einen Zeitplan, eine Statusänderung eines Tasks, eine Kommentarphrase oder einen Webhook.
Schritt 1: Den CI-Fehler an einen Webhook senden
GitHub Actions bietet ein workflow_run event, das ausgelöst wird, sobald ein anderer Workflow abgeschlossen ist. Es wird bei jedem Ergebnis ausgelöst, weshalb Sie mit einer Job-Bedingung auf failure filtern. Ein wichtiger Hinweis aus der GitHub-Dokumentation: Die Workflow-Datei muss auf dem Standard-Branch vorhanden sein, andernfalls wird sie nie getriggert.
Dieser Workflow wartet auf einen Workflow namens CI, erstellt einen kompakten JSON-Body, signiert ihn und sendet ihn ab:
name: Report CI failure
on:
workflow_run:
workflows: [CI]
types: [completed]
jobs:
notify:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
steps:
- name: Send signed webhook
env:
WEBHOOK_URL: ${{ secrets.SHARKLY_WEBHOOK_URL }}
SIGNING_SECRET: ${{ secrets.SHARKLY_SIGNING_SECRET }}
REPO: ${{ github.repository }}
RUN_ID: ${{ github.event.workflow_run.id }}
RUN_URL: ${{ github.event.workflow_run.html_url }}
BRANCH: ${{ github.event.workflow_run.head_branch }}
SHA: ${{ github.event.workflow_run.head_sha }}
run: |
BODY=$(jq -nc --arg repo "$REPO" --arg run_id "$RUN_ID" \
--arg url "$RUN_URL" --arg branch "$BRANCH" --arg sha "$SHA" \
'{event:"ci_failure",repo:$repo,run_id:$run_id,run_url:$url,branch:$branch,sha:$sha}')
TS=$(date +%s)
SIG=$(printf '%s\n%s' "$TS" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary | base64)
curl -fsS -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
--data-raw "$BODY"
Branch-Namen stammen von Mitwirkenden. Daher übergibt der Workflow sie über env und jq, anstatt sie direkt per String-Interpolation in das Shell-Skript einzufügen. Speichern Sie beide Werte als verschlüsselte Repository-Secrets und niemals direkt in der Datei.
Schritt 2: Die Automation und ihren Webhook-Trigger erstellen
Erstellen Sie in Ihrem Space eine Automation, weisen Sie sie dem Agenten zu, der die Fehler beheben soll, und fügen Sie einen Webhook-Trigger hinzu. Sharkly zeigt die vollständige URL nur ein einziges Mal an – beim Erstellen oder Neugenerieren des Triggers. Kopieren Sie sie daher direkt in das GitHub-Secret.
Aktivieren Sie ein Signing-Secret. Ohne Secret fungiert die URL als Bearer-Token: Jeder, der sie besitzt, kann einen Durchlauf starten. Mit Secret muss gemäß der Automations-Dokumentation jeder Request einen X-Webhook-Signature-Header mit v1= sowie einem Base64-codierten HMAC-SHA256 über den Zeitstempel, einen Zeilenumbruch und den Roh-Body enthalten, signiert mit dem whsec_-Secret. Sharkly lehnt Zeitstempel ab, die mehr als 300 Sekunden abweichen, und akzeptiert eine gegebene Signatur innerhalb von 10 Minuten nur einmal, sodass abgefangene Requests nicht erneut abgespielt werden können.
Der Trigger muss aktiviert und die Automation auf „Active“ gesetzt sein, bevor ein gültiger Request einen Durchlauf starten kann. Testen Sie das Ganze zuerst über „Run now“.
Schritt 3: Anweisungen schreiben – erst filtern, dann fixen
Eine Automation, die über einen Webhook ausgeführt wird, erstellt nicht automatisch einen Task. Da der Durchlauf keinen verknüpften Task hat, sollten Ihre Instruktionen explizit einen anlegen; so erhält jeder Fehler einen Datensatz, einen Diskussions-Thread für Rückfragen und einen Status, den Ihr Team einsehen kann. Platzieren Sie die einfachen Prüfungen ganz oben, damit die meisten Ereignisse in Sekundenschnelle abgehandelt sind:
You receive a CI failure webhook. The trigger payload is JSON with
event, repo, run_id, run_url, branch, sha.
1. Stop with no output unless event == "ci_failure" and repo is
acme/web. Stop if branch starts with "release/".
2. Search open tasks for run_id. If one exists, stop.
3. File a task titled "CI fix: <repo> run <run_id>" with run_url in
the body. Do all further work under that task.
4. Read the failed steps: gh run view <run_id> --log-failed
5. If the cause is a secret, permission, runner, or network problem,
comment the diagnosis on the task and stop. Change nothing.
6. Check out sha in a fresh worktree. Run the failing command and
confirm it fails the same way. If it does not reproduce, comment
what you tried and stop. Never push an unreproduced fix.
7. Make the smallest change that fixes it. Do not edit CI config,
lockfiles, or tests you were not asked to fix. Rerun the command
and the nearest test suite.
8. Push to branch ci-fix/<TASK-ID> and open a draft PR with
gh pr create --draft, task ID in the title. Comment the PR link
on the task and hand it to a human for review.
Hierbei sind zwei Details entscheidend: Status- und Kommentar-Trigger reagieren derzeit organisationsweit. Aus diesem Grund empfiehlt die Dokumentation, Eingaben innerhalb der Instruktionen zu validieren. Ein Webhook ist zwar an seine URL gebunden, aber Schritt 1 schützt zusätzlich vor versehentlich fehlgeleiteten Requests. Zudem erfüllt die Task-ID im Branch-Namen eine wichtige Funktion: Ist die GitHub-Integration angebunden, verknüpft eine Task-ID im Branch, im PR-Titel oder im PR-Body den Pull-Request automatisch wieder mit dem Task.
Schritt 4: Auf einem Computer in einem isolierten Worktree ausführen
Ein Computer ist der angebundene Host, auf dem Ihr Agent läuft – mit eigenen Runtimes, Dateien und Git-Zugangsdaten. Stellen Sie das Repository des Agenten auf den Temporary-Modus ein, damit jeder Durchlauf ein eigenes Task-Verzeichnis und einen separaten Worktree erhält. Zwei Fehler, die im Abstand von einer Minute eintreffen, können sich so nicht gegenseitig in die Quere kommen. Zu den technischen Details siehe parallele Agenten in isolierten Worktrees und die Referenz zu git-worktree.
Der Git-Zugriff erfolgt über den Computer, nicht über die GitHub-App. Die Integration verknüpft Pull-Requests und synchronisiert Issues; das Klonen und Pushen nutzt weiterhin den SSH-Schlüssel, das HTTPS-Token oder das gh-Login auf diesem Host. Erteilen Sie diesen Zugangsdaten ausschließlich Push-Rechte für Branches und schützen Sie Ihren Standard-Branch, sodass für jeden Merge ein Review erforderlich ist.
Kosten und Leitplanken
Jeder Durchlauf wird über den Tarif der jeweiligen Runtime abgerechnet. Da Sharkly keine Tokens verkauft, kostet ein CI-Fix-Durchlauf genau das, was eine Claude-Code- oder Codex-Sitzung dieser Dauer heute für Sie kostet. Der Schnellfilter in Schritt 1 ist Ihre wichtigste Kostenbremse: Ein Ereignis, das bereits bei Schritt 1 stoppt, verbraucht nur wenige hundert Tokens statt einer vollständigen Reproduktion.
Die Nebenläufigkeit (Concurrency) ist das zweite Steuerungselement. Jeder Computer verfügt über ein Limit für parallele Tasks, und Durchläufe in temporären Verzeichnissen nutzen standardmäßig die Hälfte davon. Ist die Kapazität erschöpft, werden zusätzliche Durchläufe in eine Warteschlange eingereiht, anstatt einen einzelnen Laptop zu überlasten. Ein chaotischer Vormittag mit 30 roten Builds führt somit zu einer Warteschlange, nicht zum Systemkollaps.
Die übrigen Punkte sind Regeln, die Sie einmalig festlegen:
- Ausschließlich Draft-PRs. Der Agent mergt niemals eigenständig. Unter Human-in-the-Loop-Coding-Agenten erfahren Sie, an welcher Stelle das Review-Gate sitzen sollte.
- Ein Versuch pro Durchlauf. Schlägt der erste Fix bei der erneuten lokalen Ausführung fehl, kommentiert der Agent den Task und stoppt.
- Eine Denylist: CI-Konfigurationen, Secrets, Lockfiles, Migrationen.
- Pausieren Sie die Automation auf ihrer Einstellungsseite, wenn Sie Instruktionen anpassen, und aktivieren Sie sie erst nach einem Testlauf via „Run now“ wieder.
Überprüfen Sie das System gründlich, bevor Sie ihm blind vertrauen. Hier greift der Plan-, Observe- und Verify-Loop: Analysieren Sie eine Woche lang die Ausführungshistorie, bevor Sie weitere Repositories freigeben.
Alternativen
Sie können pro Fehler auch direkt einen Task anlegen, anstatt eine Webhook-Automation zu nutzen. Richten Sie den Workflow dazu auf ein Skript aus, das sharkly task create aufruft, und lassen Sie den zugewiesenen Agenten die Arbeit aufnehmen. Dadurch erhalten Sie für jeden roten Build einen Task – auch für solche, die der Agent ignorieren sollte –, weshalb sich dieser Ansatz eher für Repositories mit geringem Aufkommen eignet. Teams, die Issues bereits über GitHub verwalten, können alternativ damit beginnen, ein GitHub-Issue an einen KI-Agenten zuzuweisen.
Mit einem Repository starten
Wählen Sie das Repository mit den meisten Lint- und Typfehlern, richten Sie den oben beschriebenen Workflow ein und führen Sie die Automation dreimal manuell aus, bevor Sie den Webhook scharf schalten. Sobald Sie mehr als einen Agenten betreiben möchten, zeigt Ihnen der Leitfaden wie man 10 KI-Coding-Agenten gleichzeitig ausführt alles Weitere. Der Einstieg in Sharkly ist kostenlos: Verbinden Sie einen Computer und überlassen Sie Ihrem bestehenden Agenten den nächsten roten Build.
FAQ
Kann ein KI-Agent fehlschlagende CI-Builds eigenständig beheben?
Er kann Lint-, Typ- und Snapshot-Fehler beheben, die er lokal reproduzieren kann. Er sollte Änderungen jedoch nicht selbstständig mergen. Behalten Sie Draft-PRs als Ausgabe bei und lassen Sie die Freigabe durch einen Menschen erfolgen.
Wie triggere ich einen KI-Agenten, wenn GitHub Actions fehlschlägt?
Fügen Sie einen Workflow für das Event workflow_run mit types: [completed] und der Job-Bedingung conclusion == 'failure' hinzu. Dieser Job sendet einen signierten Request an die Webhook-URL des Agenten.
Was hindert den Agenten daran, einen falschen Fix zu pushen?
Die Reproduktionsregel. Der Agent muss den Fehler lokal sehen, eine Änderung vornehmen und beobachten, dass derselbe Befehl erfolgreich durchläuft. Gelingt keine Reproduktion, hinterlässt er einen Kommentar im Task und pusht nichts.
Erstellt die GitHub-Integration von Sharkly Pull-Requests?
Nein. Sie verknüpft Pull-Requests mit Tasks und synchronisiert Issues. Das Öffnen des PRs übernimmt der Agent über die Git- und gh-Zugangsdaten auf seinem Computer.
Was ist mit Flaky Tests?
Lassen Sie den Agenten den fehlgeschlagenen Test mehrmals ausführen, bevor er eine Entscheidung trifft. Ist der Test in einigen Durchläufen erfolgreich und schlägt in anderen fehl, sollte der Agent das Flaky-Verhalten im Task dokumentieren, statt oberflächliche Änderungen am Code vorzunehmen.
Wie viel kostet ein CI-Fix-Durchlauf?
Die Kosten entsprechen den Tokens, die Ihre Runtime für diese Sitzung verbraucht. Sharkly-Durchläufe werden direkt über Ihren Claude-Code-, Codex- oder API-Tarif abgerechnet.
