Every field of ship.yml, generated from the same definition the platform validates against.
ship.yml lives at the root of your repository and configures everything a mission does in it:
where a preview deploys, which harness and model each
agent runs on, and how long the
retry loop keeps going.
This page is the complete field list, generated from the same schema the platform validates your
file with, so it describes exactly what will be accepted.
Worth wiring up even if you only edit the file occasionally: every block lives in one document, so a
file that fails validation takes the rest of its configuration down with it, so agents and
retries revert to platform defaults without a second complaint.
The workflow file SHIP dispatches. It must exist on your default branch for GitHub to accept the dispatch; the version that runs is the one on the pull request's branch.
configFile
string
yes
Repo-relative path to the deploy tool's configuration, passed through to your workflow.
envName
string
yes
The environment name within that configuration.
appName
string
yes
Base name for the per-PR application. The deployed name is {appName}-pr{N}-{issueId}, stable across pushes.
accountSubdomain
string
yes
Your *.workers.dev subdomain, used to build the preview URL.
previewHost
string
no
Hostname template for the preview, with {pr} replaced by the pull request number. Omit to stay on *.workers.dev. Required for anything depending on zone-level features such as image transformations.
skipDeployPaths
string[]
no
Globs marking a change as non-deployable for this target. Setting this REPLACES the built-in list. The deploy is skipped only when every changed file matches.
services
object[]
no
The previewable services in this environment. Omit it for a single deployable application, in which case the fields above are treated as one implicit service.
datastores
object[]
no
Datastores provisioned for this environment. Omit to provision none.
An alias (opus, sonnet, haiku, codex) or a concrete versioned model id, passed through unchanged.
provider
string
no
Gateway provider id for the open-model harnesses. Defaults to the harness's own.
effort
string
no
Reasoning-effort knob, mapped to each harness's native control. Harnesses without one ignore it.
providerRouting
object
no
Upstream-provider pin for gateway-routed harnesses, for deterministic runs.
checkpoint
boolean
no
Pause the pipeline after this role's stage so a human can review the handoff. QA is the terminal stage and cannot be checkpointed.
rejectOn
"critical", "suggestion", "trivial"
no
Review rejection threshold, meaningful on reviewer only. critical is the default; trivial blocks on everything.
prompt
string
no
Repo-relative path to an extra prompt file for this role, appended to SHIP's own charter and never replacing it. Wins over the default .ship/agents/<role>.md location. Up to 512 characters.
