Configure your app¶

Forge reads mithran.yaml from the repo root during manifest review. The file describes the app identity, startup command, app-environment mapping, non-secret configuration, and route exposure. Forge rejects invalid or unsupported manifest fields before it builds the image.

Your repo also needs a repo-root Dockerfile and an HTTP process that follows the HTTP app contract. The manifest tells Forge what to start; the Dockerfile builds the image that must satisfy that contract.

What to configure¶

Start with the customer-owned decisions below. Keep each decision separate so a reviewer can tell what changed and what evidence proves it.

Decision	Configure it in	Why it matters
App identity and hostname label	`metadata.app_id` and the served app ref used with onboarding, versions, and publish	Keeps the manifest identity aligned with the route users will open.
Project/app ownership	`identity.project_ref` and `map onboard --app-ref` or `--project-ref`	Keeps deploy evidence tied to the intended project/app grouping.
Process startup	`capabilities[].startup.command`	Forge records this command and the built image must be able to run it.
Runtime configuration	`non_secret_env`, `resources`, and `app_env.*.env_overrides`	Controls plain config and requested runtime shape. Secrets do not belong here.
Route exposure	`public_edge.exposure`	Controls whether Forge auth is required before traffic reaches the app. Supported manifest values are `protected`, `none`, `public-redirect`, and `public`.
Deploy refs	Built-in webhook policy, `app_env.*.auto_deploy_refs`, direct `map deploy`, or optional custom CI	Controls which refs can request deploys and which app environment receives them.
Protected sharing	`access.yaml` with `map access plan` and `map access apply`	Decides which signed-in users or domains can reach a protected app.

Use mithran.yaml reference for the exhaustive field list. Use App access and sharing for protected sharing policy and revocation paths.

Minimal deployable manifest¶

This is the smallest useful HTTP app manifest:

mithran.yaml

apiVersion: map.mithran/v1
kind: MithranApp
metadata:
  app_id: my-app
  name: My App
identity:
  project_ref: app:my-app
capabilities:
  - kind: http
    route: /
    runtime: nodejs22
    startup:
      command: npm start

This manifest can pass schema review, but the deploy still needs a Dockerfile and an app process that listens on $PORT and satisfies Forge runtime readiness. The examples in these docs also include GET /health for local checks; the manifest does not declare the serving probe path.

If map onboard --repo-dir <checkout> creates a starter file, review and edit it before the first deploy. The starter is a basic HTTP MithranApp skeleton:

mithran.yaml

apiVersion: map.mithran/v1
kind: MithranApp
metadata:
  app_id: <repo-name>
  name: <repo-name>
identity:
  project_ref: <project-ref>
capabilities:
  - kind: http
    route: /
    runtime: nodejs22
    startup:
      command: npm start

Complete HTTP example¶

Use this shape when you want an app that deploys from built-in webhook refs and serves through a Forge-authenticated app route after publish:

mithran.yaml

apiVersion: map.mithran/v1
kind: MithranApp
metadata:
  app_id: inventory-portal
  name: Inventory Portal
  description: Customer inventory portal
  tags:
    - operations
identity:
  project_ref: app:inventory-portal
capabilities:
  - kind: http
    route: /
    runtime: nodejs22
    startup:
      command: npm start
resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi
non_secret_env:
  - name: NODE_ENV
    value: production
  - name: LOG_LEVEL
    value: info
public_edge:
  type: platform
  exposure: protected
app_env:
  preview:
    branch_pattern: "^refs/heads/main$"
    image_tag: preview
  production:
    branch_pattern: "^refs/(heads/release/.*|tags/release/.*)$"
    image_tag: prod

If this app is onboarded and deployed as app:inventory-portal, the production clean public URL is:

https://inventory-portal.apps.mithran.cloud/

That URL is not moved by deploy alone. Deploy creates internal versions and app-environment aliases; map publish pins the clean public URL to one reviewed version.

App identity¶

metadata.app_id identifies the app in manifest review and evidence:

metadata:
  app_id: inventory-portal
  name: Inventory Portal

Choose an app_id that is short, lowercase, DNS-friendly, stable, and recognizable in release evidence. For self-service apps, use the matching served app ref, such as app:inventory-portal, in map onboard --app-ref, map versions, and map publish. If the app ref changes, hostname expectations change; treat that as a route-impacting change and verify the served hostname after publish.

identity.project_ref should match the project/app ref agreed during onboarding:

identity:
  project_ref: app:inventory-portal

When a repo can ship more than one customer, tenant, project, or app, confirm this value with the account operator before release.

Runtime and startup¶

An HTTP capability describes the process Forge starts:

capabilities:
  - kind: http
    route: /
    runtime: nodejs22
    startup:
      command: npm start

For self-service HTTP apps:

kind is http;
route is required for HTTP capabilities;
runtime must be present;
startup.command must be present and valid inside the built image;
the process must listen on $PORT.

Forge validates the manifest before build. Runtime readiness happens after the image builds and starts. If review passes but readiness fails, inspect runtime_status, runtime_failure, deploy evidence when available, the Dockerfile, $PORT, and the serving probe behavior.

Capability support¶

Forge manifest review accepts these capability kinds:

Capability kind	Manifest shape	Self-service docs cover	Use it when
`http`	Requires `route`, `runtime`, and `startup.command`.	Yes. This is the app shape covered by the quickstart, HTTP app contract, deploy, publish, and access docs.	The repo serves an HTTP app that listens on `$PORT`.
`worker`	Requires `runtime` and `startup.command`. `route` is not required by manifest review.	No. These docs do not define a customer self-service worker runtime contract.	Do not use it as a substitute for a documented HTTP app.
`scheduler`	Requires `route`, `runtime`, and `startup.command`.	No. These docs do not define a customer self-service scheduler runtime contract.	Do not use it as a substitute for a documented HTTP app.

runtime is required manifest metadata for every capability. It is not a substitute for the repo-root Dockerfile; Forge still builds the image from the repo and then starts the declared startup.command. The starter manifest uses runtime: nodejs22 and startup.command: npm start because the starter is an HTTP Node.js skeleton.

For customer self-service apps, use kind: http.

Plain configuration¶

Use non_secret_env only for values that are safe to commit:

non_secret_env:
  - name: NODE_ENV
    value: production
  - name: LOG_LEVEL
    value: info

Do not put API keys, tokens, private keys, passwords, customer credentials, raw secret refs, or GitHub Actions expressions in non_secret_env. Manifest review rejects obvious secret-looking names and values.

For approved secret mount metadata, use secret_bindings:

secret_bindings:
  - name: db-secret
    mount:
      kind: env
      target: DATABASE_URL
    purpose: database
    required: true
    rotation:
      required: never

secret_bindings describes the binding shape only. It must not contain secret values, secret_ref, key, or provider_ref. Use this block only when the account has approved the corresponding secret binding.

Route exposure¶

Use public_edge.exposure to set the reviewed app-route exposure value:

public_edge:
  type: platform
  exposure: protected

Exposure	Route behavior
`protected`	Forge auth is required before the request reaches the app.
`none`	Forge keeps the non-public route shape.
`public-redirect`	Forge auth is required. Use only when the reviewed manifest requires this exact value.
`public`	Forge serves the route without platform auth. Use only for apps approved for anonymous access.

Do not put WAF expressions, Cloud Armor expressions, provider-specific ingress rules, or custom DNS policy in mithran.yaml.

For protected apps, route exposure is only one part of access. Use access.yaml, map access plan, and map access apply to control which signed-in users or domains can reach the app. Applying access policy does not edit mithran.yaml and does not publish a new version.

Deploy refs and app environments¶

Built-in webhook intake creates deploy candidates for these refs:

Pushed ref	Default app environment
`refs/heads/main`	`preview`
`refs/heads/release/*`	`production`
`refs/tags/release/*`	`production`

Use app_env to record app-environment metadata:

app_env:
  preview:
    branch_pattern: "^refs/heads/main$"
    auto_deploy_refs:
      - "refs/heads/main"
    image_tag: preview
  production:
    branch_pattern: "^refs/heads/release/.*$"
    auto_deploy_refs:
      - "refs/heads/release/*"
      - "refs/tags/release/*"
    image_tag: prod

Each app_env entry needs branch_pattern and image_tag. Optional auto_deploy_refs entries must start with refs/; exact refs and a single trailing * prefix glob are supported. Reviewed auto_deploy_refs can refine the app environment for built-in webhook candidates after Forge snapshots the manifest, but they do not make arbitrary refs deployable through the built-in webhook path. Use map deploy or custom CI for refs outside the built-in webhook intake set.

The --env value in map deploy --env production is an app environment. It does not change the customer account context. See Account context and app environments.

Review before merge¶

Review manifest changes the same way you review code that changes production behavior:

Change	Review question
`metadata.app_id` and app ref	Do the manifest identity, onboarding ref, and hostname users open all match?
`identity.project_ref`	Does this attach the app to the correct project/app boundary?
`capabilities[].startup.command`	Does the command exist inside the image and start the long-running HTTP process?
`non_secret_env` or `app_env.*.env_overrides`	Are all values safe to commit, and are secret-looking names absent?
`public_edge.exposure`	Is the reviewed app-route exposure value approved by the operator?
`app_env`	Do the branch pattern, `auto_deploy_refs`, image tag, overrides, replicas, and review policy match the intended app environment?
`secret_bindings` or OAuth/public-edge policy metadata	Has the account approved the policy metadata?

Before a customer-visible release, keep the reviewed manifest, commit SHA, deploy status, map versions <app> output, publish command output when publishing is involved, and access verification when protected sharing is involved.

Common failures¶

Symptom	Likely input to inspect
`ReviewBlocked`	Missing required field, unknown field, unsupported capability shape, unsupported exposure, or secret-looking non-secret config.
`BuildFailed`	Dockerfile, dependency files, package metadata, or build context.
`RuntimeFailed`	Startup command, `$PORT` binding, serving probe response, or process exit.
Manifest review rejects exposure	Failing commit's `public_edge.exposure`; manifest review accepts `protected`, `none`, `public-redirect`, and `public`.
Push does not start a deploy	Pushed ref, built-in webhook policy, GitHub App grant, and onboarding record.

For exact status fields, use Deploy status and evidence. For symptom-specific recovery steps, use Troubleshooting.

Next¶

After the manifest is reviewed and committed, onboard the repo so Forge records the repo registration and can accept deploys from it.