Production checklist¶

Use this checklist before the first customer-visible Forge deploy and before material access changes. It is written for the developer shipping the app and the operator who owns the GitHub organization, tenant, or customer account.

The checklist assumes the app already has a working Dockerfile, mithran.yaml, and local HTTP 200 readiness response. The self-service examples also include GET /health for local checks. If you are still setting those up, start with Build with Forge.

Roles¶

Role	Owns	Signs off on
Developer	App code, Dockerfile, `mithran.yaml`, release ref, and app readiness behavior.	The commit builds, starts on `$PORT`, returns HTTP 200 on local readiness paths, and declares the intended exposure.
GitHub admin	Forge GitHub App install and repo grants.	The repo is granted to the Forge GitHub App and the grant matches the intended source-access scope.
Tenant or account operator	Tenant/account/project/app refs, protected-access readiness, and deploy evidence.	The app is attached to the correct tenant/account/project/app boundary and the evidence packet can be assembled if deploy or route behavior fails.

Preflight¶

Check	How to verify	Owner
CLI installed and signed in	`aegis doctor --json` from the target checkout reports local setup readiness.	Developer
GitHub App connected	`aegis github status --project-repo <owner/repo> --require --json` reports `state: valid` and `execution_target.ready: true` for the repo.	Developer or GitHub admin
Production account context confirmed	The setup link, GitHub App, endpoint, and hostname all belong to the customer account's production setup.	Developer and operator
App environment confirmed	`app_env` and any `map deploy --env` value match the intended app deploy target.	Developer
Repo onboarded	`map onboard` output records the repo registration; `map doctor --app <owner/repo>` has no blocking diagnostics.	Developer
Manifest reviewed	`mithran.yaml` has the expected `metadata.app_id`, `identity.project_ref`, HTTP capability, startup command, environment variables, and `public_edge.exposure`.	Developer and operator
Dockerfile reviewed	The Dockerfile builds the service that `mithran.yaml` starts.	Developer
Serving probe ready	The app listens on `$PORT` and returns HTTP 200 on the local readiness paths you use to represent serving health.	Developer
Exposure approved	`public`, `protected`, `public-redirect`, or `none` matches the user-facing intent.	Operator
Protected sharing approved	For protected apps, `access.yaml` resolves to the intended `allowed_domains` and `share` values with `map access plan`.	Operator
Custom-CI path identified	If the team uses custom CI, `.github/workflows/map-deploy.yml` exists and was generated with `--with-ci-workflow`. If not, built-in deploys use GitHub App webhooks.	Developer or release automation owner
Custom-CI variables reviewed	For custom CI, repo Variables include required `MAP_INSTALLATION_REF`, `MAP_APP_REF`, `MAP_CONTROL_ENDPOINT`, and `MAP_AUTH_ENDPOINT`. Copy the endpoint values from the account setup values; set `MAP_TENANT_REF`, `MAP_ACCOUNT_REF`, and `MAP_OIDC_AUDIENCE` only when the account setup requires them.	Developer or release automation owner

Manifest checks¶

Review these fields before the first deploy:

metadata.app_id and served app ref: keep them aligned for self-service apps so map versions, map publish, and the served hostname all refer to the same app. Keep the label stable, short, DNS-friendly, and unique for the account.
identity.project_ref: records the intended project/app ref. Confirm this with the account operator when a repo can ship apps for more than one customer, tenant, project, or app.
capabilities[].startup.command: must start the HTTP process used by Forge. The process must listen on $PORT.
non_secret_env: only plain configuration belongs here. Do not commit secrets, tokens, private keys, or customer credentials.
public_edge.exposure: records the reviewed app-route exposure value. public serves anonymously; all other values keep platform auth required. Treat exposure changes as review-required.
app_env: reviewed app-environment metadata such as branch_pattern, auto_deploy_refs, image_tag, non-secret overrides, replicas, and review policy.

For protected apps, review access.yaml alongside the manifest. map access apply does not change public_edge.exposure; it writes the protected sharing policy that route updates or route reconciles carry to the edge.

See the complete field list in mithran.yaml reference.

Release¶

Use main for a preview deploy:

git push origin main

Use one of the default production release triggers:

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

or:

git tag release/v1.0.0
git push origin refs/tags/release/v1.0.0

The push sends a GitHub App webhook to Forge. Forge checks the repo grant and onboarding record, snapshots source, reviews the manifest and source snapshot, builds the image, places the runtime, and records routing records for the version.

If an operator or automation needs to request a deploy directly, use:

map deploy --repo <owner/repo> --env production --ref <git-ref> --installation-ref <installation-ref>

That command sends a deploy request directly to the control plane. If your team uses GitHub Actions or another custom CI system, opt into and review the map-deploy.yml workflow separately. The optional workflow uses GitHub OIDC, non-secret MAP_* repo Variables, release/** branches, tags matching v[0-9]+.[0-9]+.[0-9]+, and manual dispatch; it is not the built-in webhook path. It fails before requesting a deploy when required production repo Variables are absent.

Go/no-go gates¶

Use these gates before moving customer-visible traffic. A failed gate means the release owner should stop, fix the owning input, and collect fresh evidence.

Gate	Go when	Stop when	Owner
Source access	`aegis github status --project-repo <owner/repo> --require --json` succeeds for the repo.	The repo is missing from the GitHub App grant, the grant belongs to another account context, or the status is not ready.	GitHub admin
Onboarding	`map onboard` has recorded the repo registration and `map doctor --app <owner/repo>` does not identify a missing app registration.	The installation ref, repo, tenant/account/project/app refs, or served app ref do not match the release repo.	Developer and operator
Manifest review	`mithran.yaml` at the release commit declares the intended app ID, project/app ref, startup command, app-environment metadata, and exposure.	Exposure, app identity, app-environment metadata, or non-secret config are not reviewed.	Developer and operator
Deploy health	`map --json status <deployment-ref>` shows `deployment.status.status: Succeeded` with `build_status: Succeeded`, `runtime_status: Ready`, and `route_status: Ready`.	Review, build, runtime, or route status is blocked, failed, missing, or unclear.	Developer
Publish decision	`map versions <app>` shows the internal version that matches the reviewed deployment ref, and `map publish` uses `--expected-sha` for the reviewed commit.	The version label, deployment ref, or expected SHA does not match the release evidence.	Operator
Access decision	The reviewed exposure is deployed, protected apps have reviewed `access.yaml`, successful `map access apply`, and allowed/denied verification.	The hostname serves the wrong exposure or the protected sharing policy is not proven at the served route.	Operator

Verify¶

Before moving the route for a protected app, apply the reviewed sharing policy:

map access plan --repo-dir .
map access apply --repo-dir .

After the deploy succeeds:

Confirm the deploy status is Succeeded.
Confirm build_status: Succeeded, runtime_status: Ready, and route_status: Ready.
If runtime readiness is unclear, inspect runtime_failure, deploy evidence when available, the startup command, $PORT, and the serving probe behavior.
If the app uses the clean public host, list versions with map versions and publish only a reviewed version that reached Succeeded or Promoted.
Open the app hostname returned by publish or shown in map versions. For an app served as app:my-app:

curl https://my-app.apps.mithran.cloud/

Confirm the app behavior matches the reviewed commit.
For protected apps, verify both an allowed and denied access result. If the hostname does not reflect the reviewed protected sharing policy, update or publish the route users should reach and verify again.

For publish steps and moving traffic back to a previous version, see Versions and publishing. For deploy field meanings and evidence packets, see Deploy status and evidence.

Evidence to keep¶

Keep enough evidence for an operator to reproduce the deploy path without guessing:

repo owner/name;
customer account context and app environment;
commit SHA and main, release branch, release tag, or custom-CI ref;
tenant, account, and project/app refs;
aegis github status --project-repo <owner/repo> --require --json output;
mithran.yaml at the deployed commit;
deploy status and control-plane response;
deploy evidence from map --json evidence <deployment-ref> when the endpoint has evidence;
map versions <app> output before and after publishing when the clean public URL is involved;
access.yaml, map access plan, and map access apply output when the protected sharing policy is involved;
app hostname and observed HTTP result;
GitHub Actions run URL when custom CI is involved.