Forge

Forge turns a GitHub repo into reviewed app versions and gives an operator an explicit publish step for the clean public URL. The default deploy path is the Forge GitHub App webhook: push a built-in deploy ref, Forge snapshots the source, reviews mithran.yaml, builds the image, starts the runtime, and records routing records. Publishing is separate; Forge does not move https://<your-app>.apps.mithran.cloud to a new version until map publish moves the published clean URL.

Choose a path

I need to...	Start with
Deploy a small app end to end	Quickstart
Understand the full workflow before running commands	Build with Forge
Install and grant the GitHub App for a customer account	Connect GitHub and Administer Forge
Configure mithran.yaml for an existing service	Configure your app and HTTP app contract
Review or change who can reach an app	App access and sharing
Debug a failed deploy	Deploy status and evidence and Troubleshooting
Publish or restore clean URLs	Versions and publishing
Run a canary release	Canary releases

What to know first

Rule	Why it matters
GitHub App grant, onboarding, deploy, publish, and app access are separate controls.	Each control has different evidence and a different owner. Do not use one as proof of another.
Built-in deploys come from GitHub App webhooks, not GitHub Actions.	Most repos need no workflow file. Use the optional custom-CI workflow only when customer automation must request deploys.
--app-ref is the served app identity in the self-service path.	The CLI stores it as identity.project_ref and uses it for route, version, publish, and optional custom-CI deploy requests.
App environment is not account context.	preview and production are app targets; setup link, endpoint, GitHub App, and hostname pattern come from the customer account setup.
Deploy is not publish.	A successful deploy creates a version. map publish moves the clean public URL to one reviewed version.

The default loop

The intended setup and onboarding loop is shown below. The current install and Aegis-to-Map authentication gaps block it as a customer flow:

Step	Command or action	Evidence
Install	No customer-supported signed macOS package is published today.	No customer install evidence is available.
Sign in	aegis setup	aegis doctor --json
Connect GitHub	Use the customer setup link to install or request the Forge GitHub App.	aegis github status --project-repo <owner/repo> --require --json
Configure	Add a deployable mithran.yaml and a repo-root Dockerfile.	Reviewed manifest diff and local HTTP contract check.
Onboard	Blocked: no shipped bridge connects the completed Aegis setup to the Map login state required by map onboard.	No onboarding evidence is available from this flow.
Deploy	Push main, a release/* branch, or a release/* tag.	map versions <app> and map --json status <deployment-ref>
Publish	map publish <app> --version <version> --expected-sha <sha>	map versions <app> and the published hostname response

Developer path

Step	Page
Get the tools and sign in	Install the CLI records the current package status; Sign in documents setup after Aegis is installed.
Prove GitHub access	Connect GitHub.
Make the app deployable	Configure your app and HTTP app contract.
Register the repo	Onboard a repo.
Deploy and inspect status	Deploy and Deploy status and evidence.
Publish the reviewed version	Versions and publishing.

Admin path

Step	Page
Prepare the customer account and GitHub org	Administer Forge.
Approve source access and app identity	Connect GitHub, Account context and app environments, and Onboard a repo.
Review exposure and protected sharing	App access and sharing.
Run rollout and incident procedures	Admin operations runbooks.
Keep release evidence	Production checklist.
Escalate Mithran-owned work	Support and escalation.

What you need

• A GitHub account (personal or org) where you can install a GitHub App.
• OpenAI Codex CLI (codex) and Lima with limactl on your PATH.
• A repo with an HTTP app that listens on $PORT and returns HTTP 200 for readiness checks.
• An Apple Silicon Mac to run the CLI. Builds and deploys run in Forge, so your laptop doesn't need Docker.

Current limitation: Aegis writes account state under ~/.aegis/local/state/account/session.private.json. Map reads ~/.config/mithran/login.json and requires map_control_endpoint plus the map-control audience. map login save needs an endpoint and token that aegis setup does not provide, so no shipped bridge exists and the onboarding flow shown here is blocked. This is a product defect, not a missing documentation step.

If you are not the GitHub org admin, ask the admin who manages the target org to review Administer Forge and Connect GitHub before onboarding repos.

What Forge does not do automatically

• It does not grant the GitHub App to a repo; a GitHub admin controls that.
• It does not turn every branch or tag push into a deploy. Built-in webhook deploys use main, release/* branches, and release/* tags.
• It does not move the clean public URL after every successful deploy. Publish moves that pointer.
• It does not make protected apps public when you apply access.yaml. Manifest exposure and protected sharing are separate controls.
• It does not retire a route when you remove a repo grant or disable custom CI. Route retirement is a separate support path.

What happens at release time

When you push the main branch, GitHub sends a webhook with refs/heads/main. By default, that targets the preview app environment. When you push a release/* branch or release/* tag, GitHub sends refs/heads/release/* or refs/tags/release/*. By default, those target the production app environment. Forge verifies that the repo is granted to the Forge GitHub App and registered by onboarding, snapshots source, reviews the manifest and source snapshot, builds the image, starts the runtime, and records routing records for the new version. The deploy status tells you which stage passed or failed. map publish moves the clean public URL to the reviewed version you choose.

For the full release path, see Deploy. For the admin and evidence view of the same path, see Production checklist.