Skip to content

Build with Forge

Use this path when you want to take a GitHub repo from source code to a live Forge URL and understand which evidence proves each step.

Start here

The fastest path is the Quickstart. Use this page when you want to understand the full flow before you run it, or when more than one role is involved in the first release.

Forge separates five decisions that are often mixed together in other deploy systems:

Decision Owner Where it is proven
Can Forge read this repo? GitHub admin or repo owner aegis github status --project-repo <owner/repo> --require --json
Is this repo registered to the right app/account? Developer with operator input map onboard output, including the resolved app identity, and map doctor --app <owner/repo>
Which ref should create a deploy? Developer or release automation owner Built-in GitHub App webhook ref, direct map deploy command, or optional custom-CI run.
Who can reach the route? Operator Reviewed public_edge.exposure, reviewed access.yaml, map access plan, map access apply, and allowed/denied checks.
Which version should users reach? Release operator map versions <app> and map publish output

Keep those decisions separate in review. A successful deploy can create a new version without moving the clean public URL, and a GitHub App grant can allow source fetch without publishing anything. Applying access.yaml changes the recorded protected-sharing policy; it does not edit mithran.yaml, deploy, publish, or retire a route.

Step Page Result
1 Install the CLI No customer-supported signed macOS package is published today; see the page for the current status.
2 Sign in Your local CLI has a Mithran session.
3 Connect GitHub The Forge GitHub App can read granted repos.
4 Account context and app environments You know the customer setup context and app environment you are targeting.
5 Configure your app The repo has a mithran.yaml that describes what to build and serve.
6 HTTP app contract The service builds with a Dockerfile, listens on $PORT, and satisfies Forge runtime readiness.
7 Review app access You know the supported app-route exposure value and protected sharing policy.
8 Onboard a repo Forge has a repo registration and app manifest.
9 Deploy A built-in deploy ref or explicit deploy request starts the Forge deploy path.
10 Versions and publishing You know how the clean public URL moves to a reviewed version.
11 See it live The production app hostname returns the published app.
12 Production checklist Developers and operators have the evidence needed for the first customer-visible release.

What you need

  • A GitHub account where you can install or request installation of a GitHub App.
  • OpenAI Codex CLI (codex) and Lima with limactl on your PATH.
  • A repo with an HTTP service, a Dockerfile, and a serving probe response.
  • An Apple Silicon Mac for the CLI. Builds and deploys run in Forge.
  • The Glossary if you need to distinguish Forge, MAP, aegis, map, deploy, publish, public, and protected terms.

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.

Command spine

These commands describe the intended default webhook path. The sequence is currently blocked at Map authentication by the limitation above:

aegis setup
aegis github status --project-repo <owner/repo> --require --json
map onboard --installation-ref <installation-ref> <owner/repo> --repo-dir . --app-ref <app-ref>
git push origin main
map versions <app>
map --json status <deployment-ref>
map publish <app> --version <version> --expected-sha <sha>

You can omit --app-ref when the served app ref is the default app:<repo-name>. Use it when the account operator gives you a specific app identity or when the intended hostname label is not the repo name.

Use map deploy only when an operator or automation needs to request a deploy directly. Use --with-ci-workflow only when the repo intentionally uses custom CI to request deploys.

Common checkpoints

  • Run aegis doctor --json after setup to confirm local setup state.
  • Run aegis github status --project-repo <owner/repo> --require --json to confirm the target repo's GitHub App grant.
  • Confirm the customer setup link, GitHub App, endpoint, hostname, served app ref, and app environment before onboarding or deploying.
  • Run map doctor --app <owner/repo> after onboarding to check app-specific registration and recent-deploy diagnostics.
  • Check the HTTP app contract before deploying a non-quickstart service.
  • Review App access and sharing before making a route public or treating it as protected.
  • Watch deploy status after pushing a built-in deploy ref.
  • Keep the Production checklist evidence for customer-visible deploys.
  • Use Troubleshooting if source fetch, deploy auth, route propagation, or runtime readiness fails.

If you administer the account

If you manage the GitHub org, tenant, account, or security review, start with Administer Forge before asking developers to onboard repos.

For the security model, read Security and Trust.