Steps and approvals

Every job on deploy, seed or start is a step. Phases run in a fixed order. Inside a phase, steps run in parallel unless depends_on orders them. A block step runs nothing and waits for someone to approve it. The keys are in the jobs reference.

jobs:
  init-db: { label: Create the database, service: web, command: npm run db:init, on: deploy }
  migrate: { service: web, command: npm run migrate, depends_on: [init-db] }
  assets:  { service: web, runner: tools, command: ./scripts/upload-assets.sh, on: deploy }
  release:
    block: Release to customers
    prompt: Check the canary dashboard and #support first.
    depends_on: [migrate, assets]
    environments: [production]
  seed:    { service: web, command: npm run seed, on: seed }

init-db and assets start together. migrate starts when init-db succeeds. release waits for both branches. seed starts after the whole deploy phase.

Phases

Phases are barriers. A phase starts only when every step of the one before it has succeeded.

In your environments, a rollout runs the deploy steps; see Builds. Jobs on a schedule, on destroy or with no on are not steps.

Order steps with depends_on

depends_on names jobs and services in one list. A job name makes the step run after that job succeeds. A service name makes the job wait for that service, as before.

• Parallel by default. Steps with nothing between them run at the same time, up to 8 per sandbox. Past 8, the rest start in file order as slots free up.
• Inherited phase. A job without on that depends on jobs runs in the latest phase among them. migrate above runs on deploy. A job without on that depends only on services stays on demand.
• Same or earlier phase. A step can depend on steps of its own phase or an earlier one. A seed step can list a deploy step; a deploy step can't list a start step.
• No cycles. Parity names the cycle.
• One name, one meaning. A name that is both a service and a job is an error. Rename one.

Labels

label is the name the console and CLI show for a step. The job's name stays its key: depends_on, parity run and the API use the key. A label is one line, at most 200 characters.

Block steps

A block step gates the rollout. It runs nothing: no service, command, runner or service depends_on.

release:
  block: Release to customers       # or: block: true, with label
  prompt: Check the canary dashboard and #support first.
  depends_on: [migrate, assets]
  environments: [production]

Sandboxes pass blocks. A sandbox belongs to an agent, and agents never approve. The block records as succeeded the moment its dependencies are done, so parity up never stalls on one.

Environments wait. A block holds the rollout until a person approves or rejects it. That takes environments.deploy, which Developers have. Approve lets the steps after it run. Reject fails the rollout, and the current revision keeps serving. Agent tokens can't approve.

Jobs that run something can't vary by environment. What a sandbox tested is what every environment runs. environments exists only on blocks because a block runs nothing.

When a step fails

Rerunning parity up retries the failed step. Steps that succeeded on seed or start don't run again; deploy steps run on every rollout.

Parity runs one copy of a job at a time. A rollout that lands while an earlier run of migrate is still going waits for it, so two migrations never meet one database.

Read status

Before you deploy, parity check prints each step with its label, phase and what it runs after:

jobs
  init-db (Create the database) in web, deploy: when a sandbox is set up and on every rollout
  migrate      in web, deploy: when a sandbox is set up and on every rollout, after init-db
  assets       in web, deploy: when a sandbox is set up and on every rollout
  release (Release to customers) block, waits for a person in staging and production (sandboxes pass it), deploy: when a sandbox is set up and on every rollout, after migrate, assets
  seed         in web, seed: once, when a sandbox is first set up, after the deploy jobs

While it runs, parity status, the sandbox_status MCP tool and GET /v0/sandboxes/{id} return each step under jobs, in run order:

[
  { "name": "init-db", "label": "Create the database", "event": "deploy", "status": "succeeded", "attempts": 1 },
  { "name": "migrate", "event": "deploy", "status": "running", "needs": ["init-db"], "attempts": 1 },
  { "name": "assets", "event": "deploy", "status": "failed", "attempts": 3, "log_tail": "…" },
  { "name": "release", "label": "Release to customers", "event": "deploy", "status": "skipped", "needs": ["migrate", "assets"], "block": true, "attempts": 0 }
]

Validation

parity check and parity up refuse a manifest with any of these, and list them all at once.

Migrate from file order

jobs:
  init-db: { service: web, command: npm run db:init, on: deploy }
  migrate: { service: web, command: npm run migrate, on: deploy }

jobs:
  init-db: { service: web, command: npm run db:init, on: deploy }
  migrate: { service: web, command: npm run migrate, on: deploy, depends_on: [init-db] }

Order between phases is unchanged. A seed job still runs after every deploy job and needs no depends_on for that. Run parity check to see each step's after list before you push.