AI integrations

fremforge ships three server-side AI features at Phase 1 — AI PR review, Renovate dep-bump explanations, and a customer-callable AI gateway at POST /api/v1/orgs/<slug>/ai/complete. All three run on the BYOK (bring-your-own-key) model: the customer chooses an AI vendor, pastes a vendor API key into the admin UI, and fremforge proxies calls with audit + spend tracking. The vendor is the customer’s own processor under the customer’s contract, not a fremverk sub-processor (see the trust page and DPA Annex B §B.8).

This page is the operator-facing reference for that configuration. For the developer-side AI tooling (Claude Code, Cursor, Continue, JetBrains AI talking to fremforge directly with a PAT) see get-started/ai-in-your-ide/ — different audience, different surface, different sovereignty story.

What you configure

Everything below is at /<org>/_admin/ai-integrations.

Providers

A “provider” is one AI vendor account. The customer adds as many as they want (typical: one for prod, one for staging-with-cheaper-model). Each row carries:

Label — human-readable name (e.g. anthropic-prod). Stable identity used in admin UI + satisfaction scores.
Vendor + Adapter — vendor identity (anthropic / openai / azure-openai / mistral / vertex-gemini / custom) drives which adapter handles the call (openai-compatible / anthropic / vertex-gemini).
Base URL + Default model — vendor endpoint + model identifier.
API key — encrypted at rest with AES-256-GCM using T Cloud DEW KMS root, with a per-row AAD binding. Plaintext is captured only at the moment of a vendor call.
Inline test — when you save, fremforge calls the vendor’s models-list (or equivalent) endpoint with the key. A red badge on the row means the key didn’t validate.

Feature defaults

Three features, three rows in the ai_feature_defaults table:

Feature	What it does
pr-review	Posts a structured AI review comment on every new PR. Pending → success / warning commit-status.
renovate-explanation	Adds CVE / breaking-change explanations to Renovate-authored dep-bump PRs.
workflow-callable	Routes the customer-callable `POST /api/v1/orgs/<slug>/ai/complete` endpoint.

Each row points to one provider id + optional model override. Setting enabled=false turns the feature off for the tenant.

Per-repo overrides

The customer can override the feature default on a single repo — e.g., disable AI review on a sensitive repo, or pin a regulated repo to a different model. Resolution order in AiGateway.resolveProvider():

Per-call provider_override / model_override (workflow request body)
ai_repo_overrides row for (tenant, repo_full_name, feature)
ai_feature_defaults row for (tenant, feature)
Fallback: oldest active provider for the tenant

Workflows using AI

Daily, the /jobs/sha-pin-scan cron walks every workflow YAML under .forgejo/workflows/ and detects:

A # fremforge-ai: block annotation declaring provider: + model:
Any direct call to /api/v1/orgs/<slug>/ai/complete

Both signals feed the “Workflows using AI” admin section. Use it to forecast spend, audit sovereignty, and plan key rotations.

Annotation format:

# 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":"…"}]}'

Usage rollup

Per-month aggregation of ai_usage_events — requests, tokens-in, tokens-out per tenant. Estimated euros is null at Phase 1; per-vendor pricing lookup lands later. The vendor’s invoice is the source of truth for cost — fremforge’s rollup is for forecasting + per-(provider, model) cost shaping.

Review feedback

Per-(provider, model) satisfaction score from 👍 / 👎 reactions on AI PR review comments. Polled daily from Forgejo for 14 days after each comment is posted. Below 70% renders red — consider switching model or rewriting the prompt.

Soft-fail UX

AI features never block a PR. Every failure mode maps to a soft-fail path:

Reason	Status	UX
`no_provider`	503	(silent — feature is off for this tenant)
`invalid_key`	502	Commit-status warning: “AI provider key invalid — re-add under AI integrations”
`rate_limited`	429	Commit-status warning: “AI review queued — retrying on next push”
`over_cap`	402	Commit-status warning: “AI quota exhausted this month”
`vendor_error`	502	Commit-status warning: “AI review unavailable; retry on next push”
`timeout`	504	Commit-status warning: “AI review timed out”

A customer’s CI / merge path is unaffected by any AI failure — only the AI-generated comment is missing.

PAT scope

The customer-callable POST /api/v1/orgs/<slug>/ai/complete requires a PAT carrying the ai:invoke scope. Mint at /-/settings/tokens; pick a 90-day max TTL; pass as Authorization: Bearer ffp_…. Token spend goes to the configured provider’s vendor bill, not fremforge’s Fees.

Phase 2 — turnkey AIFS

A turnkey plan tier where fremverk holds an AIFS-Germany account and bills per-seat for tokens is on the roadmap (6–18 months — gated on AIFS catalogue shipping a code-tuned model good enough for PR review). When that flips, the BYOK path stays available; the gateway’s resolveProvider() consults a turnkey flag first.

Disabling AI globally

If you need to turn AI off for the whole tenant for any reason: set every ai_feature_defaults row to enabled=false. To turn AI off platform-wide (operator-only), clear MASTER_ENCRYPTION_KEY from the api-runtime Secret and roll api — see runbooks/ai-vendor-outage.md §Glass-break.

Trust page — AI integrations data path — the customer-facing sovereignty article
DPA Annex B §B.8 — contractual carrier for the BYOK-not-sub-processor position
Per-tool IDE quick-starts — developer-side AI tooling
OpenAPI spec — POST /orgs/{org}/ai/complete is documented under tags: [AI]