Skip to main content

Deployment & Operations

Runtime modes​

ModeCommand or entry pointPurpose
Local runtimenpm run dev or npm run dev:<target>Compose the selected target with hot reload through runtime-entry.
Production buildnpm run build or npm run build:<target>Generate package/domain exports and .mastra/output for the selected workload.
Production startnpm run startRun .mastra/output/index.mjs; target-specific start scripts build first.
Hosted deploymentGitHub ActionsBuild/publish images, deploy selected services, reconcile settings/contracts, and record evidence.

Local Mastra runtime state may use .mastra/data/mastra.db; operational and domain persistence uses SQL Server/Azure SQL when configured. Do not treat the local LibSQL file as a replacement for Core.AgentProfiles or domain logs.

Deployment lane map​

The staged code-promote.yml is currently primary for supported testing targets and K12/TAP/SDAC dev. The legacy monolith remains the router fallback and scheduled compatibility lane. code-promote-collapsed.yml has been removed.

Choosing a lane​

  • Use CI for source policy, typecheck, build/runtime smoke, and path-scoped test selection.
  • Use fast deployment only when a valid promotion manifest already contains every selected image and the change does not require DB, infra, APIM, settings, or contract mutation.
  • Use Code Promote for full component selection, DACPAC, infrastructure, configuration, reconciliation, and deeper validation.
  • Use Environment Reconcile for drift repair and report/apply stages without rebuilding application images.
  • Use model-runtime deployment for Azure model capacity and Core model-table reconciliation.

Required pre-dispatch check​

node scripts/github-actions/prepare-code-promote-dispatch.mjs \
  --project testing \
  --deploy-target test \
  --source-commit HEAD

Use the returned workflowFile and command only when ok is true. Never bypass the validator merely to force a lane. Production access or mutation requires explicit approval.

Environments and components​

Environment behavior is composed from:

  • environments/** for resolved service, gateway, write-guard, and deployment declarations;
  • .github/config/projects/*.yml for promotion behavior;
  • azure_template/profiles/*.json for project component selection;
  • azure_template/environments/*.bicepparam and main.bicep for environment tier and infrastructure defaults.

The deployable surface includes runtime, Function apps, ingestion, Admin UI, Widget, Handbook App, health aggregator, diagnostics, Grafana, and internal and external docs. Exact ownership is profile-specific.

Supported stagingBootstrap deployments provision the configured model runtime automatically. For other targets, use the Deploy Model Runtime workflow and follow the model deployment guide.

Service access​

APIM normally exposes environment-specific prefixes for selected backends. The Admin UI browser path is local /admin-api/** or deployed /dashboard/admin-api/**; direct runtime /admin/** is an operator/service path protected by the runtime admin proxy secret when enabled. Consult the environment declaration and APIM policy rather than assuming every prefix or auth exemption exists in every project.

Production and rollback​

Production slot behavior is contract-driven. Environments using swapMode: external-manual require a separately approved slot/cutover process; lower environments commonly deploy directly. Check deploymentSlotNames, the environment swapMode, and the target workflow before describing a universal staging/rollback topology.

Verification​

  • Workflow/config changes: targeted tests/infra/** plus the required local promotion planner/validator.
  • Runtime/API changes: relevant typecheck/tests, generated contracts, Bruno mapping, and smoke coverage.
  • Database changes: owning SQL project, aggregate project sync, DACPAC safety, migration/seed review, and deployment ordering.
  • UI changes: app typecheck/build and deterministic desktop/mobile Playwright.

Next pages​