Support and escalation

Use this page when customer-owned checks are complete and the issue still needs Mithran review. Keep one packet per affected app so source access, deploy state, route state, access policy, and published-version state do not get mixed across apps.

Start with Troubleshooting for symptom-specific checks. Use Admin operations runbooks when the issue is part of a customer rollout, GitHub App grant change, deploy-failure investigation, or app access change.

Self-Service Boundary

Developers and customer admins can change these controls without a Mithran support action:

Customer-owned control	How to change it	What it does not do
GitHub source access	Change the Forge GitHub App repository grant in GitHub.	Does not remove an already served route or change the published clean URL.
Custom-CI deploy requests	Disable or remove .github/workflows/map-deploy.yml when the repo uses custom CI.	Does not affect built-in GitHub App webhooks or existing routes.
Manifest exposure	Change public_edge.exposure, deploy the reviewed commit, and publish when the clean public URL should move.	Does not remove the route entry itself.
Protected sharing	Review access.yaml, run map access plan, run map access apply, and move the route that should carry the policy.	Does not edit mithran.yaml, publish a version, or retire a route.
Published version	Run map publish for a reviewed version that reached Succeeded or Promoted.	Does not delete the clean public hostname.

Escalation is for the remaining Mithran-owned question after those controls are set and evidenced. Keep that boundary explicit in the packet so support can tell whether the request is source access, route state, protected access, publish state, or control-plane behavior.

Escalate When

Escalate after the developer or customer admin has collected evidence and the remaining issue points to one of these areas:

Area	Escalate when
Protected access	The app is configured for protected access, the policy has been reviewed and applied, the served route has been updated or published, and allowed/denied checks still do not match the documented model.
Route retirement	A served app route must stop serving and the customer has already chosen the matching source-access and app-access revocation steps.
Control-plane behavior	The control-plane response or deploy status does not match the documented deploy, build, runtime, route, publish, or access model.
Source fetch or deploy auth	GitHub App grant and onboarding have been verified, but source fetch or deploy authorization still fails repeatedly for the same repo.
Custom hostname or non-self-service route work	The app needs route work outside the standard self-service *.apps.mithran.cloud hostname path.

Do not escalate before confirming the repo is granted to the correct Forge GitHub App, the repo is onboarded, and the hostname matches the served app ref shown by map versions <app>, unless setup itself is the failing step. For self-service apps, also confirm the served app ref is aligned with metadata.app_id.

Do not send

Do not include raw secrets, bearer tokens, private keys, passwords, customer credentials, or full local machine paths. Send command output and control-plane responses with secret values redacted.

For custom-CI issues, include repo Variable names and non-secret values such as endpoint names and refs. Do not send GitHub OIDC tokens or access tokens.

For control-plane API errors, include the HTTP status and full redacted response body. Use API errors to classify the status before escalating.

Base packet

Include this table for every escalation:

Field	Include
Summary	One or two sentences naming the symptom, impact, and when it started.
Affected app	App hostname, metadata.app_id, served app ref, tenant ref, account ref, and project/app ref.
Repo	GitHub owner/name, source commit SHA, pushed ref, and deployment ref when available.
Account context and app environment	Customer setup link, saved endpoint, app environment, and whether custom CI uses the matching endpoint and GitHub App installation values.
GitHub App state	GitHub account or organization, App name from the customer setup link, grant mode, and whether the repo is selected or covered by all-repos access.
Manifest	mithran.yaml at the deployed or failing commit.
Deploy status	map --json status <deployment-ref> output or the control-plane response that contains deploy status.
Deploy evidence	map --json evidence <deployment-ref> output when the endpoint has evidence.
Published version	map versions <app> output when the clean public URL is involved.
User-visible result	URL tested, timestamp, HTTP status/body excerpt, browser error, access-denied result, or screenshot.
Checks already run	aegis doctor --json, map doctor --app <owner/repo>, and the troubleshooting entries already followed.

For first-release evidence, also use the Production checklist.

Scenario additions

Add the fields that match the escalation type.

Setup or GitHub App install

Field	Include
Setup command	aegis setup output from the target checkout, or browser error.
Doctor output	aegis doctor --json.
GitHub owner	User, account, or organization where the App was installed or requested.
Setup route	Whether the install was started from the customer setup link.

Onboarding or source fetch

Field	Include
Onboard command	Full map onboard command without tokens.
Onboard output	Success JSON, 409 response, or error text.
Registration check	map doctor --app <owner/repo> output from the saved Forge endpoint.
Grant evidence	GitHub App settings showing the repo grant for the App shown by the customer setup link.
Source ref	Branch, tag, or SHA requested by the deploy.

Built-in webhook deploy

Field	Include
Pushed ref	refs/heads/main, refs/heads/release/*, or refs/tags/release/*.
Commit	SHA that GitHub pushed.
Deploy status	map --json status <deployment-ref> when a deployment ref is known.
Manifest policy	app_env from the deployed mithran.yaml, including any reviewed auto_deploy_refs.

Custom-CI deploy

Field	Include
Workflow revision	.github/workflows/map-deploy.yml at the failing commit.
Actions run	GitHub Actions run URL and relevant log excerpt.
Repo Variables	Required MAP_INSTALLATION_REF, MAP_APP_REF, MAP_CONTROL_ENDPOINT, and MAP_AUTH_ENDPOINT; optional MAP_TENANT_REF, MAP_ACCOUNT_REF, and MAP_OIDC_AUDIENCE when used. Include names and non-secret values only.
OIDC step	Whether the workflow obtained a GitHub OIDC token and whether the Mithran auth exchange succeeded. Do not include tokens.

Build or runtime readiness

Field	Include
Build inputs	Dockerfile, package lockfile, dependency files, and mithran.yaml startup command.
Local check	Result of the local Docker build and serving probe check, when reproduced.
Deploy fields	build_status, build_logs_ref, build_failure_ref, runtime_status, and runtime_failure when present.
App contract	Expected $PORT, serving probe behavior, and startup command.

Route, publish, or clean public URL

Field	Include
Hostname	Exact URL tested.
App identity	metadata.app_id, served app ref shown by map versions <app>, and exact hostname tested.
Route status	route_status, route_target_ref, and deployment ref when available.
Publish state	map versions <app> output and the publish command output.
Expected version	Version label, deployment ref, and expected SHA when --expected-sha was used.

Protected access

Field	Include
Exposure	public_edge.exposure from the deployed manifest.
Access policy	access.yaml, map access plan output, and map access apply output when applied.
User or domain	User or domain that should be allowed or denied.
Observed result	Browser or API response for an allowed principal and a denied principal when available.

Route Retirement

Use this packet when an app route itself must stop serving. Removing a GitHub App grant stops new source fetches, disabling custom CI stops that workflow from requesting deploys, and changing access.yaml changes protected sharing. Those steps do not prove that an existing served route has stopped serving.

Field	Include
Route to retire	App hostname and app ref.
Source access decision	GitHub App grant state and whether new source fetches should stop.
Custom-CI state	Whether .github/workflows/map-deploy.yml is present, disabled, or absent when the repo uses custom CI.
Exposure state	Current public_edge.exposure, published version, and observed route response.
Customer-owned changes already made	GitHub App grant change, custom-CI workflow change, manifest exposure change, protected-sharing change, or publish decision already completed.
Business reason	Why the route should stop serving.

Before sending

Confirm these checks or include why they could not be completed:

• aegis doctor --json was run from the relevant developer machine or setup environment.
• map doctor --app <owner/repo> was run against the saved Forge endpoint.
• The repo is granted to the Forge GitHub App shown by the customer setup link.
• The repo has been onboarded with map onboard.
• mithran.yaml is the file from the deployed or failing commit.
• The app hostname matches the served app ref shown by map versions <app>.
• For self-service apps, the served app ref is aligned with metadata.app_id.
• For clean public URL issues, map versions <app> shows the expected or unexpected published record.
• For custom-CI issues, the Actions run URL and workflow revision are included.

Support-owned actions

These actions are not completed from the customer repo, GitHub App settings, or public CLI alone:

• reviewing protected-route behavior that still does not match the documented model after customer-owned policy and route checks;
• retiring an app route when the route itself must stop serving;
• reviewing a control-plane, deploy, route, runtime, or evidence failure that remains after customer-owned checks;
• confirming route work outside the standard self-service *.apps.mithran.cloud hostname path.

For new evidence after the packet is sent, keep the same affected app and deployment ref in the thread so the investigation remains tied to one app state.