Deploy Status and Evidence

Use this page to inspect a deploy, identify the failed stage, and collect the evidence another developer or operator needs.

Start with a Deployment Ref

Every deploy investigation needs a deployment ref.

Deploy path	Where to find it
Direct map deploy	The command prints the deployment ref in text mode. With --json, it returns deployment_ref, deployment, evidence, and remote_authority.
Built-in webhook	Run map versions <app> and copy the deployment ref from internal versions or aliases.
Optional custom CI	Use the workflow response or run map versions <app> after the workflow posts the deploy request.
Publish issue	Run map versions <app> and compare the internal version, alias, and published deployment refs.

Use JSON mode when you need fields:

map --json status <deployment-ref>
map --json evidence <deployment-ref>

Without --json, generic status and evidence reads only confirm that the request succeeded. map watch is the exception: it prints the observed phase on each poll.

Investigation Flow

Use the same sequence for developer debugging, operator review, and support packets:

1. Get the deployment ref from the deploy response or map versions <app>.
2. Run map --json status <deployment-ref>.
3. Read deployment.status.status first. That is the deploy phase.
4. Read the stage field that matches the phase: review_status, build_status, runtime_status, or route_status.
5. If status points at a failure, run map --json evidence <deployment-ref>.
6. If evidence is not found, keep the status response and deploy request response; the deploy path has not recorded an evidence object for that ref.
7. If users are reaching the clean public URL, run map versions <app> and compare the published deployment ref with the deployment ref under review.
8. Keep the command output, commit SHA, pushed ref, mithran.yaml, and observed hostname response together.

Do not use map logs as the investigation source. Status, evidence, build refs, runtime failure detail, route status, and map versions are the supported customer evidence surfaces.

Next Command by Phase

After map --json status <deployment-ref>, use deployment.status.status to choose the next command. Do not skip straight to publish or support before the phase tells you what has actually happened.

Phase or condition	Next command	Why
IntentReceived, SourceResolving, or SourceSnapshotted	map watch <deployment-ref>	The deploy is still moving through intake or source snapshot.
ReviewPending, ReviewWarned, or ReviewBlocked	map --json evidence <deployment-ref>	Review evidence can identify the manifest or source rule that blocked or warned.
BuildPending or BuildSucceeded	map watch <deployment-ref>	The deploy has not reached a terminal runtime or route result yet.
BuildFailed	map --json evidence <deployment-ref>	Evidence can include build operation, logs, provenance, SBOM, artifact digest, or failure refs.
RuntimePending or RuntimeReady	map watch <deployment-ref>	Runtime placement is still progressing or has not completed route and smoke.
RuntimeFailed	map --json evidence <deployment-ref>	Evidence and runtime_failure point at startup, $PORT, or serving probe behavior.
RoutePending or RouteReady	map watch <deployment-ref>	Route programming or smoke handling has not reached a successful terminal phase.
RouteFailed or Failed	map --json evidence <deployment-ref>	Evidence can distinguish route input, hostname, smoke, or Forge-owned failure.
Succeeded or Promoted	map versions <app>	Confirm which internal version, alias, canary split, or published record references the deployment.
RolledBack or Superseded	map versions <app>	Confirm the current routing record before deciding whether another deploy or publish is needed.
Evidence is not found	Keep map --json status <deployment-ref> and the deploy request response.	Some paths have not recorded an evidence object for the ref yet.

Commands

Command	Endpoint	Use it when
map --json status <deployment-ref>	GET /v1/map-control/deploy/status	You need the saved deploy record, status view, action records, evidence attachment, or remote-authority metadata.
map watch <deployment-ref>	Repeated GET /v1/map-control/deploy/status	You want a script to keep polling until a terminal phase, control-plane API error, or timeout.
map --json evidence <deployment-ref>	GET /v1/map-control/deploy/evidence	Status points at evidence refs, or the failure needs review, build, runtime, route, or smoke detail.
map versions <app>	GET /v1/map-control/routes/status	You need the internal version, app-environment alias, published clean URL, or active canary split that references a deployment.
map --json canary start/promote/rollback ...	POST /v1/map-control/deploy/canary	You need the exact canary action receipt returned by Forge.

map watch exits successfully only when the phase is Succeeded. It exits non-zero for terminal failure states: ReviewBlocked, BuildFailed, RuntimeFailed, RouteFailed, Failed, RolledBack, and Superseded. It also exits non-zero when the control plane returns a non-success HTTP response or when the watch times out.

Use status fields, evidence refs, build refs, runtime failure details, and map --json evidence <deployment-ref> instead of map logs.

For non-success HTTP responses from map commands, use API errors to classify the response. API errors identify whether the failure is request input, authorization, missing recorded state, a state conflict, or Forge behavior.

Response Shape

Direct deploy responses and status reads are different.

The examples below use deployment://<account-context>/production/example-123 as a sample pattern. In real output, copy the full deployment_ref value exactly as Forge returned it. Do not edit individual path segments; use Account context and app environments when you need to interpret the account-context segment separately from the app environment.

Direct deploy response

map --json deploy ... returns the terminal deploy response from the deploy request. Abbreviated shape:

{
  "status": "ok",
  "deployment_ref": "deployment://<account-context>/production/example-123",
  "deployment": {
    "deployment_ref": "deployment://<account-context>/production/example-123",
    "status": "Succeeded"
  },
  "evidence": {},
  "remote_authority": {}
}

The deployment object in a direct deploy response is the deploy status view. Read the phase at deployment.status.

Status response

map --json status <deployment-ref> returns the saved service deploy record. Abbreviated shape:

{
  "status": "ok",
  "deployment": {
    "deployment_ref": "deployment://<account-context>/production/example-123",
    "trigger_event_ref": "github-delivery://...",
    "status": {
      "deployment_ref": "deployment://<account-context>/production/example-123",
      "status": "Succeeded",
      "build_status": "Succeeded",
      "runtime_status": "Ready",
      "route_status": "Ready"
    },
    "evidence": {},
    "actions": [],
    "remote_authority": {}
  }
}

For map --json status, read the deploy phase at deployment.status.status. Stage fields such as build_status, runtime_status, and route_status are also under deployment.status.

Evidence response

map --json evidence <deployment-ref> returns only the evidence object. Abbreviated shape:

{
  "status": "ok",
  "evidence": {
    "deployment_ref": "deployment://<account-context>/production/example-123",
    "status": "RuntimeFailed"
  }
}

Evidence is recorded after the deploy path has produced evidence. If the control plane returns deployment evidence not found, use map --json status <deployment-ref> and the deploy request response first.

Lifecycle

Forge advances a deploy through source, review, build, runtime, route, and smoke. These are the customer-visible phases:

Area	Phase values	Inspect
Intake and source	IntentReceived, SourceResolving, SourceSnapshotted	Repo grant, onboarding output, requested ref or SHA, source_snapshot_ref, and source evidence.
Review	ReviewPending, ReviewWarned, ReviewBlocked	review_status, review_gate, review_ref, manifest_digest, failure_reason, and review_log in evidence when present.
Build	BuildPending, BuildSucceeded, BuildFailed	build_status, build_ref, build_operation_ref, build_logs_ref, build_failure_ref, build_provenance_ref, build_sbom_ref, and artifact_digest.
Runtime	RuntimePending, RuntimeReady, RuntimeFailed	runtime_status, runtime_failure, startup command, $PORT, and serving probe behavior.
Route and smoke	RoutePending, RouteReady, RouteFailed, Succeeded	route_status, route_target_ref, app ref, app hostname, smoke evidence, and GitHub status refs.
Terminal changes	Promoted, RolledBack, Failed, Superseded	completed_at, failure_reason, routing record state, and release or incident evidence.

RouteReady means Forge programmed the route target. Succeeded means the deploy reached the successful terminal state after route and smoke handling.

Status Fields

These fields are under deployment.status in map --json status output.

Group	Fields	What they prove
Identity	deployment_ref, intent_ref, tenant_ref, account_ref, app_ref, platform_env, app_env, release_name, completed_at	The deploy belongs to the expected account, app, account context, app environment, and release context.
Source and manifest	source_snapshot_ref, manifest_digest	Forge recorded a source snapshot and reviewed manifest digest. Use evidence for source and manifest refs when present.
Review	review_ref, review_status, review_gate, failure_reason	The manifest and source snapshot were accepted, warned, blocked, or failed before build.
Build	build_ref, build_status, build_operation_ref, build_logs_ref, build_provenance_ref, build_sbom_ref, build_failure_ref, artifact_digest	The build started, produced an artifact, or failed with build-provider evidence.
Runtime	runtime_ref, runtime_status, runtime_failure	The artifact was materialized and became healthy, or runtime startup/health failed with sanitized detail.
Route and GitHub	route_target_ref, route_status, github_check_ref, github_check_evidence_ref, github_deployment_id	Forge programmed a route target and recorded GitHub-facing status refs when present.

Use map versions <app> when status proves that a deploy succeeded but the served hostname still shows a different version. A successful deploy can update internal versions and app-environment aliases without moving the clean public URL. The clean public URL moves only when map publish pins the published record to a reviewed version.

For canary releases, use map versions <app> to inspect current route state. When a split is active, the target app-environment alias shows the canary deployment ref and weight. Promote and rollback clear the split, so map versions <app> should return to compact alias output. Keep the map --json canary ... response with the release record as the action receipt returned by Forge.

Value Reference

Field	Values
deployment.status.status	IntentReceived, SourceResolving, SourceSnapshotted, ReviewPending, ReviewWarned, ReviewBlocked, BuildPending, BuildSucceeded, BuildFailed, RuntimePending, RuntimeReady, RuntimeFailed, RoutePending, RouteReady, RouteFailed, Promoted, RolledBack, Succeeded, Failed, Superseded
review_status	Pending, Passed, Warned, Blocked, Failed
build_status	Queued, Running, Succeeded, Failed
runtime_status	Queued, Running, Ready, Failed, Released, Preempted
route_status	Queued, Running, Ready, Failed
failure_reason	StaleSha, MissingRepoGrant, SourceSnapshotFailed, ManifestMissing, ManifestValidationFailed, ReviewBlocked, ReviewFailed, BuildFailed, RuntimeFailed, RouteFailed, InvalidTransition, or an Unknown(...) value.

Evidence Contents

Evidence shape depends on the terminal state and how far the deploy progressed.

Successful deploy evidence is the smoke evidence pack with remote-authority metadata attached when present. It can include deployment identity, mode, source and route refs, GitHub status refs, fixture or descriptor refs, and a review_log when a review log was recorded.

Failed deploy evidence can include:

• evidence_pack_ref;
• mode;
• deployment_ref;
• terminal status;
• failure_reason;
• sanitized runtime_failure;
• refs for GitHub event, source snapshot, review, build, runtime materialization, route, GitHub check, and GitHub check evidence;
• build_provider details such as operation, logs, provenance, SBOM, OCI artifact, artifact digest, and failure refs;
• remote_authority;
• review_log when present.

Runtime and smoke failure details are sanitized before they are returned. Secret-looking values, bearer tokens, private keys, and local machine paths are redacted from customer-visible failure details.

Failure Triage

Symptom	Inspect	Customer or operator action
No deployment ref after a push	Pushed ref, GitHub App grant, onboarding output, and whether the repo uses custom CI.	Push a built-in deploy ref, run map deploy, use the custom-CI workflow, grant the repo to the correct Forge GitHub App, or onboard the repo.
ReviewBlocked or review_status: Blocked	review_gate, review_ref, manifest_digest, failure_reason, and review_log in evidence when present.	Fix the manifest or source issue identified by review, then deploy a new commit.
BuildFailed or build_status: Failed	build_failure_ref, build_logs_ref, build_operation_ref, Dockerfile, dependency files, and package metadata.	Fix the build input at the failing commit.
RuntimeFailed or runtime_status: Failed	runtime_failure, startup command, Dockerfile, $PORT, serving probe response, and runtime evidence.	Make the app process start, listen on $PORT, and return HTTP 200 at the serving probe path Forge checks.
RouteFailed or route_status: Failed	route_target_ref, app ref, app hostname, map versions <app>, and route evidence.	Confirm the app ref, hostname, and route target; redeploy only after the route input changes or the route failure is known transient.
Failed after RouteReady or with smoke evidence	Evidence, app hostname response, exposure value, and published record state.	Compare the failed smoke or route check with the route users are actually reaching.
Succeeded but users see another version	map versions <app> and the published record.	Publish the reviewed version with map publish, or verify the internal version route instead of the clean public URL.
Publish rejects the selected version	map versions <app>, deployment ref, reviewed source SHA, and --expected-sha.	Choose a reviewed internal version that reached Succeeded or Promoted, then retry with the reviewed Git commit SHA as --expected-sha.
Canary action did not produce the expected split	map versions <app>, map --json canary ... response, canary deployment ref, weight, and target alias behavior.	Confirm the canary deployment reached Succeeded or Promoted, the weight is 1 through 99, and promote or rollback was not already applied.

Evidence to Keep

Keep enough evidence for another operator to reproduce the deploy path:

• deployment ref;
• map --json status <deployment-ref> output;
• map --json evidence <deployment-ref> output when the endpoint has evidence;
• repo owner/name and source commit SHA or ref;
• mithran.yaml at the deployed or failing commit;
• app hostname and observed HTTP response;
• map versions <app> output when the clean public URL or canary split is involved;
• map --json canary ... output as the action receipt when a canary action is involved;
• GitHub Actions run URL and relevant log excerpt when custom CI is involved.