Deploy¶

Once a repo is onboarded, deploying is a git push. Three things trigger a deploy, and nothing else does:

A push to a release/** branch → deploys that commit to production.
A semver tag, vX.Y.Z → deploys that commit to production.
map deploy <ref> → a manual deploy through the workflow's workflow_dispatch.

A plain push to main or a feature branch does not deploy. That's deliberate: you decide when a commit ships by cutting a release.

Cut a release¶

git switch -c release/v1
git push -u origin release/v1

or tag one:

git tag v1.0.0
git push origin v1.0.0

Either push starts the map-deploy workflow in your repo's Actions tab.

What the workflow does¶

It's a thin trigger. No build or model work runs in your Actions runner; the control plane does the build and deploy server-side.

sequenceDiagram
  participant GH as GitHub Actions
  participant Auth as Forge auth
  participant CP as Control plane
  GH->>GH: mint GitHub OIDC token (aud=map-control)
  GH->>Auth: exchange OIDC token
  Auth-->>GH: short-lived Forge token
  GH->>CP: POST deploy/request (Bearer token)
  CP->>CP: review commit
  CP->>CP: build image
  CP->>CP: deploy + route
  CP-->>GH: Succeeded

There's no deploy secret in your repo. The runner asks GitHub for an OIDC token scoped to that run, trades it for a short-lived Forge token, and that token is only accepted because your repo is onboarded.

Watch it¶

The Actions log prints the control plane's response, including the deploy status. A healthy run ends with Succeeded and the build, route, and runtime all Ready.

See it live¶

curl https://<app_id>.apps.sandbox.mithran.cloud/

A release deploy serves at your bare app_id host. The certificate is issued automatically the first time the host is hit.

Manual deploys¶

map deploy <HEAD-or-sha>

Use this to redeploy a specific commit without cutting a new release branch. It's handy for re-running a deploy that failed on a transient error.

Promote and publish¶

Forge separates deploying a version from publishing it to the clean public URL. map publish points the public host at a reviewed, succeeded version. See the CLI reference for the publish model.

Troubleshooting a deploy¶

If a run fails, the Actions log has the control plane's error. The common ones (source fetch failures on new repos, unknown_hostname, and OIDC exchange rejections) are covered in Troubleshooting.