d2o-paas.yaml Reference

d2o-paas.yaml lets a Web Application or Background Worker carry some of its settings in its own repository instead of the dashboard or CLI. The settings that depend on your code — a health check path your code answers, a release command your code needs run before it starts — travel with the version that needs them. A rollback then brings back the code and the settings it was built for, together.

The file is optional. An app with no d2o-paas.yaml works exactly as it does today, reading these same settings from the dashboard or the CLI.

Where the file lives

d2o-paas.yaml sits at the root of whatever gets built:

the root of your repository; or
for an app built from a subdirectory (--source-dir), that directory.

An app built from a subdirectory only sees the file in its own directory — the same rule that already applies to its Procfile.

Fields

Field	Where	Meaning
`version`	top	The file’s format version. Optional — leaving it out means `1`, the only version this reference describes.
`release.command`	top only	A command that runs once against each new version before anything else starts. See Release command.
`process`	top, or `apps.<name>`	Which Procfile process the app runs.
`port`	top, or `apps.<name>`	The port the app listens on. Only needed for an app that listens on a fixed port instead of taking the one the platform assigns — most apps don’t need this.
`health_check.path`	top, or `apps.<name>`	A path the platform requests to confirm a new version is up, same as the app’s Health Check Path setting.
`health_check.command`	top, or `apps.<name>`	A command that must exit `0` for a new version to count as healthy. Background Workers only.
`auto_rollback`	top, or `apps.<name>`	Whether a version that never becomes healthy is automatically replaced with the last healthy one.
`singleton`	top, or `apps.<name>`	Whether the app runs at most one instance. See Singleton apps.

Set exactly one of health_check.path or health_check.command for a given app — not both.

Defaults and per-app overrides

health_check:
  path: /health

apps:
  worker:
    health_check:
      command: bin/worker-check

Top-level values are defaults for every app built from the file. An apps.<name> block overrides them for one app, field by field — <name> is the app’s name in the Environment. A repository that builds a single app can leave out apps: entirely and put everything at the top level.

release.command is the one exception: it only ever belongs at the top level, never inside apps.<name>. For a shared build that produces more than one app, it still runs only once, before the one app it’s attached to starts.

What’s not in this file

Settings that differ per Environment, or that touch your plan or your secrets, are never set here — they stay in the dashboard or the CLI:

replica count, CPU, and memory;
custom domains;
environment variables and secrets.

Checking a file

paas manifest check validates a d2o-paas.yaml file against an Environment’s apps before you push, so a typo is caught before it fails a deploy:

paas manifest check -o acme -p shop -e production

$ paas manifest check -o acme -p shop -e production
d2o-paas.yaml is valid for production

It prints errors the same way a failed deployment would, warnings as warning: … lines, and exits 1 if the file is invalid — so it’s a reasonable check to run in CI before pushing. Point it at a specific file with a path argument; without one, it reads d2o-paas.yaml from the current directory. If the file can’t be read, it prints no d2o-paas.yaml here and exits 2, so CI can tell a missing file from an invalid one.

Errors

An invalid file fails validation outright. Every error names the line and the field:

d2o-paas.yaml line 3: unknown field `heath_check`

Unknown fields are errors — a typo in a field name is never silently ignored.
environments, databases, buckets, and services are reserved for future use and give their own message:
```
d2o-paas.yaml line 1: `environments` is not supported yet
```

An unsupported version gives:

d2o-paas.yaml line 1: version 2 isn't supported; use 1 or leave it out

Beyond that, the same rules as the matching app settings apply: a health check path starts with / and is at most 100 characters; a health check command is 1–500 characters and only valid for Background Workers; a port is between 1 and 65535; singleton is true or false; a release command is 1–1000 characters; a process name uses only letters, digits, - and _ (at most 63 characters).
The file itself must be at most 16 KiB.

On push, an invalid file fails the deployment immediately — no build starts, and the error is printed as remote: lines on the push, the same way a rejected push reports any other problem.

A promotion, a manual deployment (paas deploy), or a rollback with paas rollback --to refuses a version whose file is invalid: that deployment fails before its release command runs, and nothing already running is touched:

Your d2o-paas.yaml is invalid: line 3: unknown field `heath_check`

Rolling back a deployment — paas deploys rollback, the deployment page’s Roll back button, or an automatic rollback — never fails over the file: putting the previous version back must not be blocked. If that version’s file doesn’t validate, it goes back with the app’s settings left as they are.

Warnings

Warnings appear on the deployment timeline but never fail it:

an apps.<name> entry doesn’t match any app in this Environment — expected if the same file is shared across Environments with different apps, for example:
```
d2o-paas.yaml has settings for `ghost`, which isn't an app in this environment
```
process: <name> doesn’t match any line in the Procfile;
the Procfile’s release: line overrides the app’s Release command setting — see Release command;
singleton: true is set while the app’s own settings ask for more than one instance, or for autoscaling — the version deploys as a singleton anyway (one instance, autoscaling off), and the warning says so.

Read-only settings

A field the running version’s d2o-paas.yaml (or Procfile, for the release command only) sets can’t be changed from the dashboard or CLI while that version is live:

In the dashboard, the field is read-only, shows the value that runs, and is marked “from d2o-paas.yaml at abc1234” (or “from Procfile”). Under it, “Used if your code stops setting this” shows the app’s own setting.
paas apps info shows the value that runs, followed by where it comes from.

From the CLI, changing it fails:

`health_check` is set in d2o-paas.yaml at abc1234; change it there

`release_command` is set by the Procfile's `release:` line; change it there

A file that sets singleton: true also blocks scaling past one instance:

this app is a singleton because d2o-paas.yaml sets `singleton: true`, so it runs one instance; change it there to run more

Push a version whose file no longer sets that field, and the dashboard or CLI setting applies again immediately. Before your first deployment with a d2o-paas.yaml in it, nothing is locked yet.

Rollbacks

A rollback restores the settings of the version it goes back to, exactly as they were built — its d2o-paas.yaml, its Procfile, both together. If the version you’re rolling back to had no file, rolling back also hands any locked fields back to the dashboard or CLI setting.

Example

release:                 # top level only: belongs to the codebase
  command: bin/migrate

health_check:            # top-level values are defaults for every app built from this code
  path: /health

apps:                    # per-app values, keyed by the app's name in the environment
  worker:
    process: worker      # Procfile process to run
    health_check:
      command: bin/worker-check
    singleton: true

Next steps

Procfile — what runs, and how an app picks a process
Move Settings Into Your Repo — a worked walkthrough
Deployments, Health Checks & Rollback — health checks and the release command in full
Deploying with Git Push

Keyboard shortcuts