KI-Integrationen

fremforge liefert drei serverseitige KI-Funktionen: KI-Review von Pull Requests, Erklärungen zu Renovate-Abhängigkeits-Updates und ein vom Kunden aufrufbares KI-Gateway unter POST /_app/api/v1/orgs/<slug>/ai/complete. Alle drei laufen nach dem BYOK-Modell (Bring Your Own Key): Der Kunde wählt einen KI-Anbieter, fügt einen API-Schlüssel des Anbieters in die Verwaltung ein, und fremforge leitet die Aufrufe weiter, mit Audit und Erfassung der Ausgaben. Der Anbieter ist der eigene Auftragsverarbeiter des Kunden unter dessen Vertrag, kein Unterauftragsverarbeiter von fremverk (siehe die Trust-Seite und AVV Anhang B §B.8).

Wohin die Aufrufe gehen. Jeder Aufruf an deinen Anbieter verlässt fremforge nur über einen eingeschränkten ausgehenden Proxy, und nur an den Host des Anbieters, so wie er beim Speichern des Anbieters geprüft und festgepinnt wurde: eine https-Adresse mit DNS-Namen, nie eine IP-Adresse oder eine private, interne oder link-lokale Adresse. Weiterleitungen werden nicht befolgt. Ein Aufruf an einen anderen Host wird abgewiesen, schaltet die Funktion ab und wird im Audit-Log erfasst (ai.feature.auto_disabled). Der Proxy sieht nur Host und Port der verschlüsselten Verbindung, nie den Prompt oder die Antwort.

Diese Seite ist die Referenz für Administratoren zu dieser Konfiguration. Für die KI-Werkzeuge auf Entwicklerseite (Claude Code, Cursor, Continue, JetBrains AI, die mit einem PAT direkt mit fremforge sprechen) siehe KI in deiner IDE: andere Zielgruppe, andere Oberfläche, andere Souveränitätsgeschichte.

Was du einrichtest

Alles Folgende liegt unter /<org>/_admin/ai-integrations.

Anbieter

Ein „Anbieter“ ist ein Konto bei einem KI-Anbieter. Der Kunde fügt so viele hinzu, wie er will (typisch: einen für Produktion, einen für Staging mit günstigerem Modell). Jede Zeile enthält:

Bezeichnung: ein lesbarer Name (z. B. anthropic-prod). Stabile Kennung, die in der Verwaltung und bei den Zufriedenheitswerten verwendet wird.
Anbieter und Adapter: Die Identität des Anbieters (anthropic / openai / azure-openai / mistral / vertex-gemini / custom) bestimmt, welcher Adapter den Aufruf übernimmt (openai-compatible / anthropic / vertex-gemini).
Basis-URL und Standardmodell: Endpunkt des Anbieters und Modellkennung.
API-Schlüssel: im Ruhezustand mit AES-256-GCM verschlüsselt, mit T Cloud Public DEW KMS als Root und einer AAD-Bindung pro Zeile. Klartext entsteht nur im Moment eines Aufrufs beim Anbieter.
Integrierter Test: Beim Speichern ruft fremforge mit dem Schlüssel den Endpunkt des Anbieters auf, der die Modelle auflistet (oder ein Gegenstück). Eine rote Markierung an der Zeile bedeutet, dass der Schlüssel nicht gültig war. Die Markierung wird auch rot, wenn der Anbieter den Schlüssel bei einem echten Aufruf ablehnt (HTTP 401 oder 403), etwa nachdem er beim Anbieter widerrufen wurde; die Zeile zeigt also nie weiter einen alten erfolgreichen Test. Speicherst du den Anbieter erneut, wird der Schlüssel erneut geprüft und die Markierung zurückgesetzt.

Wer welchen Anbieter betreibt

Jede Kachel eines Anbieters und jeder Anbieter, den du hinzugefügt hast, zeigt, wer ihn betreibt. Die API meldet dasselbe als operator_jurisdiction an jedem Anbieterobjekt.

Anbieter	Betrieben
Mistral	In der EU betrieben
Scaleway Generative APIs	In der EU betrieben
Azure OpenAI	In den USA betrieben, auch wenn die Ressource in einer EU-Region liegt
Anthropic	In den USA betrieben
OpenAI	In den USA betrieben
Google Vertex Gemini	In den USA betrieben
Custom	Hängt vom Endpunkt ab: Die URL, die du eingibst, entscheidet

Ein in den USA betriebener Anbieter wird von einem US-Unternehmen geführt, daher kann US-Recht Zugriff auf die Daten verlangen, die er verarbeitet, auch wenn diese Daten in der EU gespeichert sind. Siehe den Auftragsverarbeitungsvertrag §11.3 und Anhang B §B.8.

Standardwerte der Funktionen

Fünf Funktionen, je eine Zeile in der Tabelle ai_feature_defaults:

Funktion	Was sie tut
pr-review	Schreibt bei jedem neuen Pull Request einen strukturierten KI-Review-Kommentar. Commit-Status pending → success / warning.
renovate-explanation	Ergänzt Pull Requests für Abhängigkeits-Updates von Renovate um Erklärungen zu CVEs und Breaking Changes.
workflow-callable	Bedient den vom Kunden aufrufbaren Endpunkt `POST /_app/api/v1/orgs/<slug>/ai/complete`.
autofix	Schlägt einen Korrektur-Pull-Request für einen kuratierten SAST-Befund vor, wenn eine Person auf KI-Korrektur klickt (KI-Korrektur). Braucht außerdem eingeschaltete KI-Korrekturen in den SAST-Einstellungen, die standardmäßig aus sind.
active-work-semantic	Semantischer Abgleich für Active work: fragt deinen Anbieter, ob zwei laufende Arbeiten im selben Repository dieselbe Arbeit sind. Schickt Titel, Anfänge von Beschreibungen, Branch-Namen und Ordner der obersten Ebene, nie Code; ein Feld mit Zugangsdaten darin wird weggelassen. Braucht eingeschaltetes Active work und einen Anbieter mit festgepinntem Host; wird nur in der Konsole eingeschaltet und ist aus, bis ein Org-Owner es einschaltet.

Jede Funktion ist aus, bis du sie einschaltest. Einen Anbieter hinzuzufügen schaltet nichts ein: Eine Funktion läuft nur dort, wo ihre Zeile enabled=true sagt (setze den Haken bei Aktiviert und speichere, oder PUT /_app/api/v1/orgs/<slug>/ai/feature-defaults/<feature>). Die Konsole zeigt jede Funktion als An oder Aus. Eine Zeile kann außerdem den Anbieter und eine Modell-Überschreibung wählen; ohne gewählten Anbieter nutzt eine eingeschaltete Funktion deinen neuesten aktiven Anbieter.

Bis zum 2026-10-19 nutzte eine Funktion ohne gespeicherten Standard deinen neuesten Anbieter, sodass das Hinzufügen eines Anbieters jede Funktion einschaltete, auch das KI-Review von Pull Requests. Das ist nicht mehr so.

Überschreibungen pro Repository

Der Kunde kann den Standard einer Funktion für ein einzelnes Repository überschreiben, etwa KI-Review für ein sensibles Repository abschalten, es nur für ein Repository einschalten oder ein reguliertes Repository auf ein anderes Modell festlegen.

Ob eine Funktion läuft, entscheidet für ein Repository: die Zeile in ai_repo_overrides für (tenant, repo_full_name, feature), falls es eine gibt, sonst die Zeile in ai_feature_defaults für (tenant, feature), sonst aus. Für eine ausgeschaltete Funktion wird nichts von dem Folgenden herangezogen, auch keine Anbieter-Überschreibung pro Aufruf.

Welchen Anbieter sie nutzt, in AiGateway.resolveProvider():

provider_override / model_override pro Aufruf (Request-Body des Workflows)
Der Anbieter der Repository-Überschreibung
Der Anbieter des Funktionsstandards
Rückfall: der neueste aktive Anbieter der Organisation

Workflows, die KI nutzen

Täglich durchläuft der Cron /jobs/sha-pin-scan jedes Workflow-YAML unter .forgejo/workflows/, .gitea/workflows/ und .github/workflows/ und erkennt:

Eine Block-Annotation # fremforge-ai:, die provider: und model: angibt
Jeden direkten Aufruf von /_app/api/v1/orgs/<slug>/ai/complete

Beide Signale speisen den Verwaltungsbereich „Workflows, die KI nutzen“. Nutze ihn, um Ausgaben vorherzusagen, die Souveränität zu prüfen und Schlüsselrotationen zu planen.

Format der Annotation:

# fremforge-ai:
#   provider: anthropic-prod
#   model: claude-opus-4-7

name: ai-summary
on:
  pull_request:
    types: [opened]
jobs:
  summarize:
    runs-on: fremforge
    steps:
      - name: Call AI
        run: |
          curl -sf https://frem.sh/_app/api/v1/orgs/<org>/ai/complete \
            -H "authorization: Bearer $FREMFORGE_TOKEN" \
            -H "content-type: application/json" \
            -d '{"messages":[{"role":"user","content":"…"}]}'

Nutzungsübersicht

Monatliche Zusammenfassung von ai_usage_events: Anfragen, eingehende und ausgehende Tokens pro Organisation. Der geschätzte Euro-Betrag ist derzeit null; eine Preisermittlung pro Anbieter ist geplant. Maßgeblich für die Kosten ist die Rechnung des Anbieters; fremforges Übersicht dient der Vorhersage und der Kostensteuerung pro (Anbieter, Modell).

Rückmeldungen zu Reviews

Zufriedenheitswert pro (Anbieter, Modell) aus 👍- / 👎-Reaktionen auf KI-Review-Kommentare in Pull Requests. Wird 14 Tage lang nach jedem Kommentar täglich von Forgejo abgefragt. Unter 70 % wird er rot angezeigt; erwäge dann, das Modell zu wechseln oder den Prompt umzuschreiben.

Sanftes Fehlschlagen

KI-Funktionen blockieren nie einen Pull Request. Jede Fehlerart führt zu einem sanften Fehlschlagen:

Grund	Status	Darstellung
`no_provider`	503	(still: die Funktion ist für diese Organisation aus)
`invalid_key`	502	Warnung im Commit-Status: „AI provider key invalid — re-add under AI integrations“
`rate_limited`	429	Warnung im Commit-Status: „AI review queued — retrying on next push“
`over_cap`	402	Warnung im Commit-Status: „AI quota exhausted this month“
`vendor_error`	502	Warnung im Commit-Status: „AI review unavailable; retry on next push“
`timeout`	504	Warnung im Commit-Status: „AI review timed out“

Der CI- und Merge-Weg eines Kunden bleibt von jedem KI-Fehler unberührt; es fehlt nur der KI-generierte Kommentar.

PAT-Scope

Der vom Kunden aufrufbare Endpunkt POST /_app/api/v1/orgs/<slug>/ai/complete braucht ein PAT mit dem Scope ai:invoke. Erstelle es unter /-/settings/tokens; wähle eine Laufzeit von höchstens 90 Tagen; übergib es als Authorization: Bearer ffp_…. Die Token-Ausgaben gehen auf die Rechnung des eingerichteten Anbieters, nicht auf die Gebühren von fremforge.

Phase 2: schlüsselfertiges AIFS

Eine schlüsselfertige Tarifstufe, bei der fremverk ein AIFS-Konto in Deutschland hält und Tokens pro Nutzer abrechnet, steht auf der Roadmap (6–18 Monate; abhängig davon, dass der AIFS-Katalog ein auf Code abgestimmtes Modell liefert, das für Reviews von Pull Requests gut genug ist). Kommt es dazu, bleibt der BYOK-Weg verfügbar; resolveProvider() im Gateway prüft dann zuerst eine Markierung für den schlüsselfertigen Tarif.

KI global abschalten

Musst du KI aus irgendeinem Grund für die ganze Organisation abschalten: Setze jede Zeile in ai_feature_defaults auf enabled=false (eine Funktion ohne Zeile ist ohnehin aus) und entferne jede Überschreibung pro Repository, die eine Funktion einschaltet. Um KI plattformweit für deine Organisation zu deaktivieren, wende dich an den Support.