How Forge works

You don't need any of this to ship. But when something behaves oddly, it helps to know what's underneath.

The control plane

Every deploy goes through one place: the control plane. It reviews commits, kicks off builds, and programs the edge to route your app. Your GitHub Actions run never builds anything itself. It asks the control plane to deploy a specific commit, and the control plane decides what happens from there.

That single chokepoint is what lets Forge enforce a review gate, keep an audit trail, and run deploys the same way no matter who triggered them.

Review before build

When a deploy comes in, the control plane reviews the commit before it builds. The review is recorded with the deploy, so every running version traces back to a reviewed commit. A failed review stops the deploy; it doesn't quietly ship.

Keyless auth

Your deploy workflow holds no secret. When it runs, it asks GitHub for an OIDC token scoped to that one run, and trades it at Forge's auth service for a short-lived token that the edge accepts. Forge only mints that token for a repo that's been onboarded, so an arbitrary repo can't deploy even if it copies your workflow.

In practice, there's no credential to rotate or leak, and you revoke a repo's access by removing its onboarding entry.

Routing and TLS

Apps serve on a wildcard, *.apps.sandbox.mithran.cloud. When the control plane finishes a deploy, it tells the edge which host maps to your app. The certificate for that host is issued on demand the first time someone hits it, so a brand-new app gets HTTPS without you requesting a cert.

This is also why a just-deployed host can briefly return unknown_hostname: the route hasn't reached the edge yet. It resolves in seconds.

Tenancy

Every app belongs to a (tenant, account, project). Onboarding writes that binding, and the control plane checks it on every deploy and source fetch. Adding a tenant or a repo is a live registry write. It takes effect immediately, with no restart, which is why onboarding feels instant.

Not a single point of failure

The control plane runs as more than one replica, sharing state so any replica can handle any request. If one falls over mid-deploy, another picks up the work. You won't see this; it's why a deploy doesn't fail when a node restarts.

Access: public vs protected

Each app declares who can reach it with public_edge.exposure. public serves anyone (this portal runs public). protected is the access-as-code model: you declare allowed domains and a share list of named users, the edge enforces it per request, and you change sharing by editing a file and re-applying it — not by clicking around a UI. The protected model is being built; for now apps use public.