How Forge works

Use this page when you need the operating model behind Forge: what objects exist, what changes during a deploy, what publish changes, which controls are owned by the customer, and which evidence proves the state of an app.

For component diagrams, see Forge architecture. For exact deploy-status fields and evidence packets, see Deploy status and evidence.

Core model

Forge turns a GitHub repo into a routed app by combining four customer-owned inputs with Forge-managed deploy infrastructure.

Area	Customer owns	Forge owns
Source	GitHub repo, commit, Dockerfile, app code, and mithran.yaml.	Source fetch for repos granted to the Forge GitHub App.
Identity	Tenant, account, project, app ref, and GitHub App repository grant.	Authorization checks that bind deploy requests to onboarded repos and granted source access.
Release intent	Built-in deploy ref, explicit deploy request, or optional custom-CI workflow.	Deploy intake, review, build, runtime placement, route programming, and status recording.
User access	Manifest exposure, protected-access policy, and publish decision.	Edge routing, protected-access checks, version routing, and deploy evidence.

The important rule is that these controls are separate. Removing source access does not by itself retire a served route. Publishing a version does not change the GitHub App grant. Changing access policy does not create a new app version unless the app manifest also changes and deploys.

Objects you will see

Object	Where it appears	What it means
Tenant	Onboarding inputs, CLI output, deploy records.	Customer authorization boundary.
Account	Onboarding inputs, access policy, CLI output.	Business account or workspace under the tenant.
Project	mithran.yaml, onboarding inputs.	Grouping that ties an app to a repo or product area.
App	metadata.app_id, app:<id>, hostnames, map versions.	The service Forge deploys and routes.
Account context	Setup URL, GitHub App, control-plane endpoint, hostname wildcard, tenant/account refs.	Customer account boundary for setup, source access, API access, and hostnames.
App environment	app_env in mithran.yaml, deploy status, map deploy --env.	App-level target such as preview or production.
Deployment ref	Deploy response, map status, map evidence, map versions.	Stable ID for one deploy attempt and its evidence.
Internal version	map versions <app>.	Addressable version created by a successful deploy.
Published clean URL	map versions <app>, map publish.	The clean public URL pinned to one reviewed version that reached Succeeded or Promoted.

Account context and app environments are different values. A production app environment does not change the setup link, GitHub App, endpoint, or hostname pattern. See Account context and app environments.

Deploy lifecycle

A deploy snapshots one Git ref, reviews it, builds it, starts the runtime, routes it, and records status. The built-in webhook path starts when GitHub sends Forge a deploy-ref event for an onboarded repo.

Stage	What Forge does	What the customer checks
Trigger	Receives a built-in deploy-ref webhook or explicit deploy request.	Ref is expected, repo is granted to the Forge GitHub App, repo is onboarded.
Source snapshot	Fetches source through the Forge GitHub App grant.	Repo grant includes the repo and the requested ref exists.
Review	Reviews the manifest and source snapshot before build.	mithran.yaml is present, valid, and declares the intended app contract.
Build	Builds the app image from the committed source.	Dockerfile, lockfiles, package metadata, and build context are correct.
Runtime	Starts the app and checks runtime readiness.	App listens on $PORT; Forge can receive HTTP 200 for readiness checks.
Route	Programs routing records for the app version and app environment.	The app ref matches the expected hostname.
Smoke and evidence	Checks the routed app and records evidence.	Status and evidence explain the result.

Built-in deploys use these default refs:

Ref pushed to GitHub	App environment
refs/heads/main	preview
refs/heads/release/*	production
refs/tags/release/*	production

Feature branches and tags such as v1.2.3 are not built-in deploy triggers. Manifest app_env entries can include reviewed auto_deploy_refs that resolve which app environment receives a built-in webhook deploy candidate. They do not make arbitrary refs deployable through the built-in webhook path. Teams that need GitHub Actions or another custom CI system to decide when to request deploys can use the optional custom-CI workflow. See Deploy.

Deploy is not publish

Forge separates version creation from customer-visible traffic movement.

Action	What changes	What does not change
Deploy	Creates deploy status, evidence, an internal version, and app-environment routing records when it succeeds.	The clean public URL is not moved just because a deploy succeeded.
Publish	Pins the clean public URL to one reviewed version that reached Succeeded or Promoted.	Source access, onboarding, app manifest, protected-access policy, and deploy records are not changed.

Use map versions <app> to see internal versions, app-environment aliases, and the published clean URL. Use map publish <app> --version <version> to move the clean public URL. Use --expected-sha <sha> when a human reviewed a specific commit and the publish must bind to that commit. See Versions and publishing.

Request path

User traffic reaches Forge before it reaches the app process.

1. A browser or API client opens the app hostname.
2. Forge edge selects the routing record for that hostname.
3. If the route is protected, Forge checks access before forwarding.
4. The app process receives the request only after edge routing and access checks pass.

The app still owns its own business logic and app-level authorization. Forge controls the platform route, Forge auth gate, protected sharing policy, and whether a route is absent from the public edge.

Source access, deploy access, and app access

These controls answer different questions:

Control	Question it answers	Where to change it
GitHub App grant	Can Forge read this repo for source fetch?	GitHub App settings for the App shown by the customer setup link.
Onboarding record	Is this repo registered to the intended tenant, account, project, and app?	map onboard from the repo checkout.
Deploy trigger	Which refs can start deploys?	Built-in webhook policy, direct map deploy, or optional custom-CI workflow.
Manifest exposure	Which reviewed app-route exposure value should the manifest use?	public_edge.exposure in mithran.yaml.
Protected sharing policy	Which users or domains can reach a protected app?	access.yaml, map access plan, and map access apply.
Published clean URL	Which reviewed version does the clean public URL serve?	map publish.

For revocation paths, see App access and sharing.

Evidence and source of truth

Use the narrowest source that proves the question you are asking.

Question	Evidence to use
Did setup and GitHub connection work?	aegis doctor --json.
Is the repo onboarded?	map onboard output. Use map doctor --app <owner/repo> as an additional diagnostic.
Did a deploy start and where is it now?	map --json status <deployment-ref> or map watch <deployment-ref>.
Why did a deploy fail?	map --json evidence <deployment-ref> plus the deploy status fields.
Which version is published?	map versions <app>.
What source and manifest were deployed?	Commit SHA, mithran.yaml at that commit, deploy status, and deploy evidence.
Which users should reach a protected app?	Reviewed access.yaml, map access plan, and map access apply output.

Keep evidence with the release or incident record. A useful operator packet includes repo owner/name, commit SHA, customer account context from the setup link and saved endpoint, app environment, tenant/account/project/app refs, deploy status, deploy evidence when available, mithran.yaml, access.yaml when protected sharing is involved, app hostname, observed HTTP response, map versions output when the clean public URL is involved, and the GitHub Actions run URL when custom CI is involved.

How to reason about failures

Start from the failed stage instead of guessing.

Failed area	What to inspect first	Likely owner of the fix
Setup or GitHub App install	aegis doctor --json, setup URL, GitHub App owner and repo grant.	Developer or GitHub org admin.
Onboarding	map onboard output, map doctor --app, tenant/account/project/app refs.	Developer with account operator input.
Source fetch	GitHub App grant, requested ref, deploy status.	GitHub org admin or developer.
Review	review_gate, review_ref, failure_reason, deploy evidence.	Developer or reviewer of mithran.yaml.
Build	build_status, build_logs_ref, build_failure_ref, Dockerfile, dependencies.	Developer.
Runtime readiness	runtime_status, runtime_failure, $PORT, startup command, deploy evidence when available, and serving probe behavior.	Developer.
Route	route_status, app ref, hostname, publish state.	Developer or operator.
Protected access	Exposure, access policy, signed-in user or domain, and allowed/denied verification.	Operator.
Published version	map versions, publish command output, expected SHA.	Operator.

The full symptom catalog is in Troubleshooting.

Responsibilities by workflow

Workflow	Developer responsibility	Admin or operator responsibility
First setup	Install CLI, run setup, confirm local doctor output.	Approve or install the Forge GitHub App when GitHub requires admin approval.
Repo onboarding	Add or review mithran.yaml, run map onboard, confirm map doctor.	Provide tenant/account/project refs and approve repo grant.
First deploy	Push a built-in deploy ref or request a deploy, then inspect status.	Confirm the app environment, exposure, and evidence packet.
Customer-visible publish	Provide commit SHA, version, hostname, and app behavior evidence.	Publish the reviewed version and keep release evidence.
Access change	Change manifest exposure or access policy in reviewed files.	Approve exposure intent, apply access policy, move the served route when the route must carry updated sharing policy, and verify allowed and denied results.
Incident review	Provide app code, manifest, status, evidence, and observed behavior.	Classify source, deploy, route, access, or publish control and escalate with a complete packet.

Common mental model checks

If you think...	Check this instead
"I deployed, so users should see it."	Deploy creates a version. Publish moves the clean public URL.
"--env production changes the account setup."	--env selects the app environment. Account context comes from setup, endpoint, GitHub App, and hostname.
"Removing the GitHub App grant removes the served app."	The grant stops new source fetches. Route retirement is a separate access decision.
"Protected access lives inside my app."	Forge checks protected access at the edge before the request reaches the app process.
"Default deploys run in GitHub Actions."	Built-in webhook deploys run through the Forge control plane. Use the workflow only for repos that need custom CI to request deploys.
"A failed deploy needs a log stream first."	Start with deploy status and evidence. Build logs and runtime failure refs are attached to the deploy record when available.