> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Application manifest schema

> Define one application, its services, environments, bindings, attached resources, cron jobs, and domains.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## 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

<Steps>
  <Step>
    Create `stackshift.yaml` with `stackshift init --name APPLICATION`.
  </Step>

  <Step>
    Describe services and their source, build, runtime, network, and environment settings.
  </Step>

  <Step>
    Declare attached databases, buckets, cron jobs, and project domains.
  </Step>

  <Step>
    Reference secret values with `fromEnv` instead of writing them into YAML.
  </Step>

  <Step>
    Run local and server validation before planning changes.
  </Step>
</Steps>

## 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

```yaml theme={null}
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.

```bash theme={null}
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

<Check>
  The manifest passes strict local parsing and the server accepts it for reconciliation planning.
</Check>

## Common failures

<Warning>
  * 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.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Initialize, validate, plan, apply, and export" href="/cli/plan-and-apply">
    Use the application manifest lifecycle with stale-plan protection, explicit pruning, and optional deployment.
  </Card>

  <Card title="Deploy Git revisions and local directories" href="/cli/deployments">
    Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.
  </Card>
</CardGroup>