Security and Trust¶

This page is for security reviewers, CISOs, and admins who need the security model, customer-owned controls, and review evidence for Forge adoption.

Security model at a glance¶

Area	Model
Deploy authentication	Built-in webhook deploys are authorized through the Forge GitHub App grant, webhook, and repo onboarding. Custom-CI deploys use the optional workflow when the repo opts into it.
Customer repo secrets	Built-in webhook deploys do not require a stored deploy secret, deploy key, or personal access token in the customer repo.
Source access	The Forge GitHub App reads source from repos where the customer has granted access.
Build and deploy control	The Forge control plane receives deploy requests, snapshots source, reviews the manifest and source snapshot, builds images, places runtimes, programs routes, and records evidence.
App access	Apps declare exposure in `mithran.yaml`. `public` serves anonymously; `protected`, `none`, `public-redirect`, and unset exposure keep platform auth required before traffic reaches the runtime.
Protected sharing	Protected routes can be narrowed with `access.yaml` using verified email domains, named email addresses, or `account:` principals.
Manifest secrets	`non_secret_env` is plain configuration only. Secret-looking names or values are rejected, and `secret_bindings` carry binding metadata rather than raw secret values.
Runtime boundary	Customer code runs as an app process behind the Forge edge. Route and version selection happen before traffic reaches the app.
Evidence	Forge deploy status and control-plane responses show deploy stage status, review/build/route/runtime results, and failure reasons. Runtime failure details, unsafe refs, and source-snapshot public evidence are constrained to non-secret summaries or safe refs. Custom-CI deploys also have GitHub Actions logs.

Trust boundaries¶

flowchart LR
  subgraph Customer["Customer boundary"]
    Admin[GitHub org or tenant admin]
    Repo[GitHub repo]
    Manifest[mithran.yaml and Dockerfile]
    OptionalWorkflow[custom-CI workflow]
  end

  subgraph Forge["Forge boundary"]
    Auth[Forge auth]
    CP[Control plane]
    Review[Review gate]
    Build[Build service]
    Runtime[Managed runtime]
    Edge[Forge edge]
  end

  Admin -->|grants repo access| App[Forge GitHub App]
  Repo --> Manifest
  Repo --> OptionalWorkflow
  Repo -->|built-in deploy ref| Webhook[GitHub App webhook]
  Webhook --> CP
  OptionalWorkflow -->|custom-CI deploy request| CP
  CP -->|source fetch for granted repo| App
  App --> Repo
  CP --> Review
  CP --> Build
  CP --> Runtime
  CP --> Edge
  Edge --> Runtime

The customer controls the source repo, GitHub App grant, app manifest, release intent, custom-CI workflow configuration when used, and app-level data handling. Forge controls deploy authorization, source fetch through the granted GitHub App installation, review of the manifest and source snapshot before build, build execution, runtime placement, health observation, route programming, smoke checks, and deploy evidence.

Credential path¶

sequenceDiagram
  participant GH as GitHub App webhook
  participant Auth as Forge auth
  participant CP as Control plane
  participant App as Forge GitHub App
  participant Repo as GitHub repo

  GH->>CP: notify built-in deploy ref
  CP->>CP: check GitHub App grant
  CP->>CP: check repo onboarding
  CP->>App: fetch source for granted repo
  App->>Repo: read source
  Repo-->>App: source snapshot
  App-->>CP: source snapshot
  CP->>CP: review manifest and source snapshot

Built-in webhook deploys do not store a Forge deploy secret. They also do not need a GitHub personal access token, deploy key, or cloud provider key. Source access is granted by the customer through the Forge GitHub App, and that grant can be limited to selected repositories in GitHub.

Custom-CI deploys use the optional map-deploy.yml workflow. That workflow does not store a Forge deploy secret. It requests a GitHub Actions OIDC token, exchanges it with Mithran auth for a short-lived map-control token, and sends a deploy request to the control plane with repo Variables. The generated workflow requires MAP_CONTROL_ENDPOINT, MAP_AUTH_ENDPOINT, MAP_INSTALLATION_REF, and MAP_APP_REF to be set in GitHub Actions Variables from account setup. MAP_TENANT_REF and MAP_ACCOUNT_REF are optional repo Variables. MAP_OIDC_AUDIENCE is optional and defaults to map-control. The workflow does not store a fallback endpoint.

Review before build¶

After source snapshot, Forge reviews the manifest and source snapshot before it builds the app. A failed review stops the deploy path before build and route programming. A successful deploy returns stage status so developers and admins can see where a deploy passed or failed.

Review also enforces the customer-facing manifest boundary:

Manifest area	Security check
`non_secret_env`	Values are treated as non-secret configuration. Secret-looking names, secret refs, and secret-looking values are rejected.
`secret_bindings`	Bindings must describe the binding name, mount, and purpose. Raw secret values and raw secret refs are not accepted in the manifest.
`public_edge`	`public_edge.type` must be `platform`, and exposure must be one of the documented values. Provider-specific WAF or ingress expressions are not accepted in `mithran.yaml`.

App access boundary¶

The app access decision sits at the Forge edge, outside the app process:

protected, none, public-redirect, and unset exposure keep platform auth required before the request reaches the runtime.
public serves the app route without platform auth.
For protected routes, allowed_domains admits signed-in users whose verified email domain matches the policy, and share admits named emails or account: principals.
A protected route with no allowed_domains and no share entries admits any signed-in user.

The production clean public URL uses the served app ref label, such as https://my-app.apps.mithran.cloud/ for an app served as app:my-app. For exposure values, protected status, sharing, domains, and revocation paths, see App access and sharing.

Operational evidence¶

For a security review or incident review, collect:

the GitHub repo and GitHub App grant scope;
the mithran.yaml revision and any custom-CI workflow revision;
the main ref, release ref, custom-CI ref, or explicit deploy request trigger;
the GitHub Actions run log when custom CI is involved;
map --json status <deployment-ref> output with review, build, route, and runtime status;
map --json evidence <deployment-ref> output when the endpoint has evidence;
the app hostname and exposure value.

These artifacts let an admin trace a running app back to the reviewed repo state and the deploy request that created it.

Customer-visible deploy evidence and status are for diagnostics, not for carrying secrets. Runtime failure details that contain bearer-token text, token-like or secret-like material, private-key markers, passwords, local home paths, or agent-local paths are replaced with a non-secret failure summary. Unsafe runtime, build, route, and smoke refs are rejected or omitted from public responses. Source-snapshot public evidence omits raw manifest content and raw snapshot error messages.

Security review FAQ¶

Does Forge require deploy secrets in customer repos?¶

No for built-in webhook deploys. They use GitHub App webhooks and repo onboarding, and the customer repo does not need a stored Forge deploy secret, GitHub personal access token, deploy key, or cloud provider key. Custom-CI paths use the optional workflow generated with --with-ci-workflow; that workflow uses GitHub OIDC and non-secret repo Variables instead of a stored Forge deploy secret.

Which repos can Forge read?¶

Forge can read repos granted to the Forge GitHub App installation. GitHub admins choose all repositories or selected repositories during installation and can change the grant in GitHub settings.

Can a copied workflow or webhook deploy from any repo?¶

No. Forge only accepts deploys for repos that are granted to the Forge GitHub App and onboarded in Forge. Custom-CI deploys also need a valid GitHub OIDC exchange and a deploy request for the onboarded repo; copying a workflow file into an ungranted or unonboarded repo is not enough.

Does protected access replace app-level authorization?¶

No. Protected access is a platform edge control before traffic reaches the app. The app still owns its own business logic, data handling, and any application-specific authorization decisions.

What happens when a signed-in user is not shared on a protected app?¶

The edge denies the request before forwarding it to the app runtime. A missing or invalid session is an authentication failure; a signed-in user who does not match the protected sharing policy receives an access denial instead.

Where do account-specific commitments live?¶

These public docs describe the product security model. Certification, data residency, retention, SSO, SCIM, SIEM export, support SLA, and availability commitments are account-specific commercial or compliance commitments.

What Forge does not ask you to put in a repo¶

Built-in webhook deploys do not need:

a long-lived Forge deploy secret;
a GitHub personal access token;
a deploy key for Forge;
a cloud provider key.

If a webhook deploy does not start, use Webhook deploy does not start. If a custom-CI deploy fails during the GitHub Actions workflow run or deploy request setup, use Custom-CI deploy auth fails.