Application manifest schema

Live. This area is documented as current, user-reliable behavior.

Goal

Write a valid stackshift.com/v1 application manifest without embedding secret values.

Prerequisites

An application design with at least one web, worker, or cron service

Workflow

Create stackshift.yaml with stackshift init --name APPLICATION.

Describe services and their source, build, runtime, network, and environment settings.

Declare attached databases, buckets, cron jobs, and project domains.

Reference secret values with fromEnv instead of writing them into YAML.

Run local and server validation before planning changes.

Document identity and ownership

apiVersion must be stackshift.com/v1.
kind must be Application.
metadata.name names the single application owned by the manifest.
spec.services must contain at least one service.
Unknown YAML fields are rejected instead of being ignored.

Complete field example

apiVersion: stackshift.com/v1
kind: Application
metadata:
  name: commerce
spec:
  teamId: 10000000-0000-4000-8000-000000000001
  services:
    api:
      type: web
      repository: stackshiftCloud/commerce
      branch: main
      rootDirectory: apps/api
      installCommand: npm ci
      buildCommand: npm run build
      startCommand: npm start
      runtime: nodejs
      deploymentRuntime: containerd
      visibility: public
      port: 3000
      env:
        NODE_ENV:
          value: production
        DATABASE_URL:
          fromEnv: COMMERCE_DATABASE_URL
          secret: true
      bindings:
        - database: primary
          env: DATABASE_BINDING
    worker:
      type: worker
      repository: stackshiftCloud/commerce
      branch: main
      rootDirectory: apps/worker
      startCommand: npm run worker
      visibility: private
      bindings:
        - service: api
          env: API_URL
  environments:
    production:
      branchPattern: main
      autoDeploy: true
      services:
        api:
          env:
            LOG_LEVEL:
              value: info
  databases:
    - name: primary
      id: 20000000-0000-4000-8000-000000000002
  buckets:
    - name: uploads
      id: 30000000-0000-4000-8000-000000000003
  cronJobs:
    nightly-report:
      service: worker
      schedule: "0 2 * * *"
      command: npm run report
      enabled: true
  domains:
    - service: api
      name: api.example.com

Service fields

type: web, worker, or cron.
repository, branch, and rootDirectory: source selection.
installCommand, buildCommand, and startCommand: build and process commands.
runtime: nodejs, go, python, static, php, ruby, or rust.
deploymentRuntime: auto, containerd (or runc), or kata.
visibility: omitted, public, or private.
port: 0 through 65535; omit it when the service does not listen.
env: variable definitions keyed by uppercase environment variable name.
bindings: service or database connections exposed through a named environment variable.

Environment overrides

Each named environment can declare a branch pattern, automatic deployment behavior, and service-specific environment variables. Every service referenced by an environment must also exist in spec.services.

Secrets

A secret variable must use fromEnv; secret: true with an inline value is rejected. At apply time, the CLI looks first in --env-file, then in the process environment. Resolved secret values are sent separately from the manifest document. They are not written into generated manifests, exported manifests, or plan output.

export COMMERCE_DATABASE_URL='postgres://...'
stackshift validate --file stackshift.yaml
stackshift apply --file stackshift.yaml

Validation constraints

Service and cron-job keys must be DNS labels of at most 63 characters.
Environment variable and binding names must match [A-Z_][A-Z0-9_]*.
A binding must choose exactly one service or database target.
Database and bucket references require a name or ID and cannot be duplicated.
Cron jobs require an existing service, a non-empty schedule, and a command.
Domains require an existing service, contain a dot, and are unique case-insensitively.

Expected result

The manifest passes strict local parsing and the server accepts it for reconciliation planning.

Common failures

The manifest uses an unknown field or a different API version.
A secret contains an inline value instead of fromEnv.
A binding references an undeclared service or database.
An environment override references a service not declared in spec.services.
A required process or env-file value is missing during apply.

Initialize, validate, plan, apply, and export

Use the application manifest lifecycle with stale-plan protection, explicit pruning, and optional deployment.

Deploy Git revisions and local directories

Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.

​Goal

​Prerequisites

​Workflow

​Document identity and ownership

​Complete field example

​Service fields

​Environment overrides

​Secrets

​Validation constraints

​Expected result

​Common failures

​Related guides

Initialize, validate, plan, apply, and export

Deploy Git revisions and local directories

Goal

Prerequisites

Workflow

Document identity and ownership

Complete field example

Service fields

Environment overrides

Secrets

Validation constraints

Expected result

Common failures

Related guides