AI integrations

fremforge ships three server-side AI features — AI PR review, Renovate dep-bump explanations, and a customer-callable AI gateway at POST /_app/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 Public 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. The badge also turns red when the vendor refuses the key (HTTP 401 or 403) on a real call, for example after the key was revoked at the vendor, so the row never keeps showing an old successful test. Saving the provider again tests the key again and clears it.

Who operates each vendor

Each vendor tile, and each provider you have added, shows who operates it. The API reports the same as operator_jurisdiction on every provider object.

A US-operated vendor is run by a US company, so US law can require access to the data it processes even when that data is stored in the EU. See the Data Processing Agreement §11.3 and Annex B §B.8.

Feature defaults

Four features, one row each in the ai_feature_defaults table:

Every feature is off until you switch it on. Adding a provider switches nothing on: a feature runs only where its row says enabled=true (tick Enabled and save, or PUT /_app/api/v1/orgs/<slug>/ai/feature-defaults/<feature>). The console shows each feature as On or Off. A row can also pick the provider and a model override; with no provider picked, an enabled feature uses your newest active provider.

Until 2026-10-19 a feature with no saved default used your newest provider, so adding a provider switched every feature on, AI PR review included. That is no longer so.

Per-repo overrides

The customer can override the feature default on a single repo — e.g., disable AI review on a sensitive repo, switch it on for one repo only, or pin a regulated repo to a different model.

Whether a feature runs for a repo: the ai_repo_overrides row for (tenant, repo_full_name, feature) if there is one, else the ai_feature_defaults row for (tenant, feature), else off. Nothing below is consulted for a feature that is off, a per-call provider override included.

Which provider it uses, in AiGateway.resolveProvider():

1. Per-call provider_override / model_override (workflow request body)
2. The repo override’s provider
3. The feature default’s provider
4. Fallback: the newest 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 /_app/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 currently null; per-vendor pricing lookup is planned. 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:

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 /_app/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 (a feature with no row is already off), and remove any per-repo override that switches a feature on. To disable AI platform-wide for your tenant, contact support.

Related

• 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]