This page lists every field of ship.yml, from the same definition that SHIP validates the file against.
ship.yml is at the root of your repository. It configures everything that a mission does in that
repository. This includes where a preview deploys, which harness
and model each agent runs on, and how long the
retry loop continues.
This page lists every field. It comes from the same schema that SHIP uses to validate your file, so
it describes exactly what SHIP accepts.
Configure your editor for the schema even if you edit the file only sometimes. All blocks are in one
document, so a file that fails validation loses all of its configuration. Then agents and
retries return to the platform defaults, and no second error tells you.
The branch that agents start from and open their pull request against. The default is main. Set it to develop or a release branch to work from that branch.
deployments
object
yes
The preview environments, keyed by name. The pipeline reads the preview key. The block is required, so if there is nothing to deploy, write an empty block.
agents
object
no
The harness, model and prompt for each role. A role that you omit uses the platform defaults.
mcp
object
no
The location of your MCP server file. See MCP servers.
retries
object
no
How long the build → CI → review → QA loop continues before SHIP hands the mission back to a person.
qaSurface
object
no
How QA tests the change when there is no deployed preview URL. By default, SHIP detects it from your project.
qa
object
no
How QA signs in to your preview to verify pages that need a sign-in. See QA sign-in.
The workflow file that SHIP dispatches. It must exist on your default branch, or GitHub does not accept the dispatch. The version that runs is the one on the pull request's branch.
configFile
string
yes
The repository-relative path to the configuration of your deploy tool. SHIP passes it to your workflow.
envName
string
yes
The environment name in that configuration.
appName
string
yes
The base name for the application that SHIP deploys for each pull request. The deployed name is {appName}-pr{N}-{issueId}, and it stays the same across pushes.
accountSubdomain
string
yes
Your *.workers.dev subdomain. SHIP uses it to build the preview URL.
previewHost
string
no
The hostname template for the preview. SHIP replaces {pr} with the pull request number. If you omit it, the preview stays on *.workers.dev. It is required for anything that needs zone-level features, such as image transformations.
skipDeployPaths
string[]
no
Globs that mark a change as not deployable for this target. A value here REPLACES the built-in list. SHIP skips the deploy only when every changed file matches.
services
object[]
no
The services in this environment that can have a preview. For a single deployable application, omit it. Then SHIP treats the fields above as one implicit service.
datastores
object[]
no
The datastores that SHIP provisions for this environment. If you omit it, SHIP provisions none.
An alias (opus, sonnet, haiku, codex, gpt) or a versioned model id. An alias always resolves to the newest model of its family. SHIP passes a model id through unchanged. The default is opus on claude-code.
provider
string
no
The gateway provider id for the open-model harnesses. The default is the harness's own provider.
effort
string
no
The reasoning effort, which SHIP maps to the native control of each harness. On claude-code, it must be low, medium, high, xhigh or max, or the stage fails before it starts. A harness without an effort control ignores it.
providerRouting
object
no
An upstream provider pin for harnesses that route through a gateway. Use it for deterministic runs.
checkpoint
boolean
no
Pause the pipeline after the stage of this role, so that a person can review the handoff. QA is the last stage, and you cannot set a checkpoint on it.
rejectOn
"critical", "suggestion", "trivial"
no
The review rejection threshold. It applies to reviewer only. critical is the default. trivial blocks on findings of every severity.
prompt
string
no
The repository-relative path to an extra prompt file for this role. SHIP appends it to its own charter and never replaces the charter. It takes priority over the default .ship/agents/<role>.md location. Up to 512 characters.
sandbox
string
no
The name or id of the sandbox (from the console) that the agent of this role starts in. It takes priority over the repository's .ship/sandbox.Dockerfile and the project's default sandbox. Up to 200 characters.
size
unknown
no
The container size for this role: standard-1 to standard-4, or { vcpu, memoryMib, diskMb }. It takes priority over the default size of the sandbox.
mcp
unknown[]
no
A filter on the MCP servers that this role receives. The servers and their credentials come from the MCP bindings of the project. List server names, or use { server, tools } to also limit the tools. It can only remove access that a binding grants, and it can never add access. Up to 32 entries.
The repository-relative path of the file that declares your MCP servers, such as .cursor/mcp.json. It takes priority over the path set on the project in SHIP. If neither is set, SHIP reads .mcp.json. SHIP reads this field from your base branch, so a pull request cannot change its own. Up to 256 characters.
A sign-in that needs no secret, which QA follows on the preview. SHIP reads it from your base branch, so a pull request cannot change its own. Without it, criteria that need a sign-in fail as unverifiable.
The sign-in page, relative to the preview origin, such as /login. It must start with one / and contain no backslashes or spaces. Up to 200 characters.
steps
string
yes
What to do on that page, in plain words. QA follows the steps with ordinary browser actions. The steps are committed and shown to the agent, so never put a password or token in them. Up to 2000 characters.
