Account Context and App Environments

Forge uses two different values during deploy work. Keep them separate:

• Account context comes from the customer setup link, GitHub App, saved CLI endpoint, hostname pattern, and Mithran-supplied setup values. Customer deploys use the production setup supplied for that customer account.
• App environment is the app-level target selected by deploy rules or map deploy --env, such as preview or production.

A customer release packet should use the setup link, endpoint, GitHub App, and hostname supplied for that customer account. Do not reuse setup values from another account.

Account Context

Account context answers these questions:

Question	Where to check
Which GitHub App should read the repo?	The Forge GitHub App shown by the customer setup link.
Which endpoint should the CLI use?	The endpoint saved by setup or login for the customer account.
Which hostname should users open?	The clean public URL returned by map publish or shown by map versions <app>.
Which account owns the app and access policy?	The tenant, account, project, and app refs used during onboarding and access review.

Use aegis doctor --json, repo-scoped aegis github status --project-repo <owner/repo> --require --json, and map doctor --app <owner/repo> to confirm setup and repo registration.

Some API responses may include account-context fields. Treat them as service-owned values, not customer inputs. Do not derive account context from app_env, branch names, workflow dispatch input, or hostnames.

App Environments

App environments describe which app target a deploy belongs to. They live in mithran.yaml:

mithran.yaml

app_env:
  preview:
    branch_pattern: "^refs/heads/main$"
    image_tag: preview
  production:
    branch_pattern: "^refs/(heads/release/.*|tags/release/.*)$"
    image_tag: prod

By default, built-in webhook deploys target the preview app environment for refs/heads/main and the production app environment for refs/heads/release/* or refs/tags/release/*. Manifest auto_deploy_refs can refine app-environment resolution for those built-in webhook candidates. Explicit deploy requests can target an app environment:

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

The --env flag is an app environment selector. It does not change account context, GitHub App, endpoint, or hostname pattern.

Release Evidence

For audit, incident review, or escalation, record:

• customer setup link or account setup source;
• saved CLI endpoint context;
• GitHub App name and repo grant state;
• tenant, account, project, and app refs;
• app environment, such as preview or production;
• pushed built-in ref, explicit deploy request ref, or custom-CI ref;
• app hostname;
• mithran.yaml at the deployed commit;
• deploy status, map versions output, and publish command output when the clean public URL is involved.

Common Mistakes

Mistake	Result	Fix
Treating map deploy --env production as an account setup change.	The deploy targets the production app environment, but the setup context is unchanged.	Use the customer setup link, saved endpoint, and GitHub App for the account.
Treating the workflow dispatch env input or mithran.yaml app_env as account context.	Custom CI sends a deploy request for the wrong app target or setup context.	Use workflow dispatch env only for the app environment, and keep endpoint, GitHub App, and tenant/account setup values from the customer account packet.
Opening a hostname from another account context while investigating an issue.	The observed route may not be the route users are using.	Confirm the app hostname from map publish or map versions <app>.
Reusing setup evidence from another account.	The evidence packet does not prove the right GitHub App grant or control-plane state.	Collect evidence from the account's active setup link, endpoint, and GitHub App.