docs: enterprise-platform vision — Forgejo as the control plane #10

Open

plat wants to merge 1 commit from docs/enterprise-platform into main

plat commented

2026-06-24 18:37:29 +00:00

Owner

The alignment artifacts you asked for — concise, direct, and built to be merged. Start at docs/vision/enterprise-platform.md.

The one idea

We don't need to build a control plane. Forgejo is the control plane. Identity, org/team RBAC, per-repo permission levels, a secret store with a UI, webhooks, notifications — it's all already there, and the platform already runs on it. Every enterprise capability is a matter of reading the Forgejo primitive we aren't yet reading and deriving the runtime from it. That single discipline is what keeps the platform cohesive as it grows — and what lets you hand it to a stranger.

Three artifacts

vision/enterprise-platform.md — the north star: the one idea, three pillars, the growth loop (webhooks as an agentic event bus → org-created build-out, "get this up and integrate to app X", notifications as the human-in-the-loop channel, the platform building itself via the agent-work loop already shipped in plat/agents#2), and a roadmap of small agent-work-able issues you can hand straight to the platform.
design/forgejo-rbac-and-access.md — apps private by default, gated at one Traefik forwardAuth edge on a single API call (…/collaborators/{user}/permission): anon → login, internal → any logged-in, none → request access, read → use, write → manage. Self-serve secrets are Forgejo's own Actions-secrets UI (write-gated for free) synced into the app — no new UI, no Vault for the default path. Domains ride repo fields + DNS verification.
design/multitenancy-and-agent-identity.md — "an agent run is the user, scoped." Retire the admin god-PAT; the run acts as its triggering user and (on apps they manage) gets a per-app, namespaced, read-only kube token for context. Authz on repo permission, not org membership. The few missing DOS bounds. So an adversary — or a prompt-injected agent — can damage at most their own corner.

Why you can trust it

Every load-bearing claim was validated against the live platform and throwaway k3d clusters, not asserted:

The permission API returns owner|admin|write|read|none per user×repo (verified: non-members → none).
Forgejo has a native repo+org Actions-secrets store with a UI (it already holds REGISTRY_TOKEN).
ResourceQuota rejects over-limit pods; an app pod's default ServiceAccount gets 403 from the kube API; a per-app namespaced read-only Role grants pods/logs in its namespace only — not another tenant, not secrets, not the cluster, not mutate.

It then passed a three-lens adversarial review (groundedness / skeptical-maintainer / completeness); the fixes — including a real blocker (the OAuth proxy mints bearer tokens, not cookies, so the session layer is genuinely new) and a hardcoded plat.sh/owner label — are applied.

What I'd love from you

Read the vision, then the two design docs. Comment on the Open questions, and if a pillar is right, approve it — each design lays its build out as phased, per-repo PRs, written so the platform can build them on itself.

The alignment artifacts you asked for — concise, direct, and built to be merged. Start at [`docs/vision/enterprise-platform.md`](docs/vision/enterprise-platform.md). ## The one idea **We don't need to build a control plane. Forgejo *is* the control plane.** Identity, org/team RBAC, per-repo permission levels, a secret store with a UI, webhooks, notifications — it's all already there, and the platform already runs on it. Every enterprise capability is a matter of *reading the Forgejo primitive we aren't yet reading* and *deriving the runtime from it*. That single discipline is what keeps the platform cohesive as it grows — and what lets you hand it to a stranger. ## Three artifacts - **`vision/enterprise-platform.md`** — the north star: the one idea, three pillars, the growth loop (webhooks as an agentic event bus → org-created build-out, "get this up and integrate to app X", notifications as the human-in-the-loop channel, the platform building itself via the agent-work loop already shipped in `plat/agents#2`), and a roadmap of small `agent-work`-able issues you can hand straight to the platform. - **`design/forgejo-rbac-and-access.md`** — apps **private by default**, gated at **one Traefik `forwardAuth` edge** on a single API call (`…/collaborators/{user}/permission`): anon → login, `internal` → any logged-in, `none` → *request access*, `read` → use, `write` → manage. Self-serve secrets are **Forgejo's own Actions-secrets UI** (write-gated for free) synced into the app — no new UI, no Vault for the default path. Domains ride repo fields + DNS verification. - **`design/multitenancy-and-agent-identity.md`** — **"an agent run is the user, scoped."** Retire the admin god-PAT; the run acts as its triggering user and (on apps they manage) gets a per-app, namespaced, **read-only** kube token for context. Authz on **repo permission**, not org membership. The few missing DOS bounds. So an adversary — or a prompt-injected agent — can damage at most their own corner. ## Why you can trust it Every load-bearing claim was **validated against the live platform and throwaway k3d clusters**, not asserted: - The permission API returns `owner|admin|write|read|none` per user×repo (verified: non-members → `none`). - Forgejo has a native repo+org Actions-secrets store with a UI (it already holds `REGISTRY_TOKEN`). - ResourceQuota rejects over-limit pods; an app pod's default ServiceAccount gets **403** from the kube API; a per-app namespaced read-only Role grants pods/logs in *its* namespace **only** — not another tenant, not secrets, not the cluster, not mutate. It then passed a **three-lens adversarial review** (groundedness / skeptical-maintainer / completeness); the fixes — including a real blocker (the OAuth proxy mints bearer tokens, not cookies, so the session layer is genuinely new) and a hardcoded `plat.sh/owner` label — are applied. ## What I'd love from you Read the vision, then the two design docs. Comment on the **Open questions**, and if a pillar is right, approve it — each design lays its build out as phased, per-repo PRs, written so the platform can build them on itself.

plat added 1 commit

2026-06-24 18:37:29 +00:00

docs: enterprise-platform vision + Forgejo-RBAC design (alignment artifacts) 62aab81469

Three focused, code-anchored artifacts for the "Forgejo is the control plane"
direction — to read, align on, and merge before the builds they describe.

- vision/enterprise-platform.md — the north star: one idea (Forgejo IS the
  control plane), three pillars, the growth loop (webhooks as an agentic event
  bus, org-created build-out, notifications as human-in-the-loop, the platform
  building itself via the agent-work loop), and a roadmap of agent-work-able
  issues the platform can build on itself.
- design/forgejo-rbac-and-access.md — apps private-by-default, gated at one
  Traefik forwardAuth edge on the repo-permission API (anon / internal / read /
  write tiers); self-serve secrets via Forgejo's own Actions-secrets UI (Vault
  demoted to optional); domains via repo fields + DNS verification.
- design/multitenancy-and-agent-identity.md — "an agent run is the user,
  scoped": retire the admin god-PAT, per-app namespaced read-only kube token,
  repo-permission authz (not org membership), DOS bounds, webhook HMAC.

Grounded against the live platform + throwaway k3d clusters: the Forgejo
permission API, the native Forgejo secret store, ResourceQuota enforcement, the
default-SA-has-no-kube-API result, and the scoped per-app Role blast radius were
all validated. Passed a three-lens adversarial review (groundedness / maintainer
/ completeness); fixes applied.

These refine the earlier per-issue proposals (#2 secrets, #3 domains) with the
RBAC lens — most notably, Forgejo's own secrets UI as the elegant default.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

plat referenced this pull request

2026-06-30 22:02:28 +00:00

Cold-start: fresh germination can stall on the ci-builder CI build (orphaned run, KEDA won't re-scale a runner) #19

plat referenced this pull request

2026-07-01 00:22:18 +00:00

self-serve secrets #2

~~plat referenced this pull request 2026-07-01 21:32:11 +00:00~~

wb-gate: activate whole whiteboard on fresh germination (lib.sh trim fix + set-u fix + CIBTAG 0.2.0) + seed refresh (mcp 0.26.0/agents 0.7.5 + _app-template#6) #61

plat referenced this pull request

2026-07-06 14:52:45 +00:00

[ROADMAP] First Client Deploy → Governance — tracker #47

plat referenced this pull request from a commit