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, or when the declared sign-in does not work on the preview. 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.
The surface that QA tests. auto detects it from your project.
build
string
no
A build command that overrides the detected one.
serve
string
no
A local serve command that overrides the detected one. It must bind servePort.
servePort
integer
no
The port that the served app listens on. It cannot be 3000, because the sandbox reserves that port. 1024-65535.
distPath
string
no
The unpacked extension directory, for browser-extension.
entry
string[]
no
The entry pages to test, for browser-extension.
specPath
string
no
The repository-relative path to an OpenAPI document, for api. If you omit it, SHIP detects the document.
onPreviewSignInBlocked
"local-surface", "unverifiable"
no
What QA does when the preview loads but the declared sign-in does not work. With local-surface, the default, QA builds and serves your change locally, checks the signed-in criteria there, and says so in its report. With unverifiable, QA stays on the preview, and those criteria are unverifiable.
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 real password or token in them. A fixture password is allowed only for an account that account.seededIn names. Up to 2000 characters.
account
object
no
The account that the steps sign in with, when each preview seeds it into its own database.
readyTimeoutSec
integer
no
How many seconds QA waits for the sign-in page to load on a new preview before it decides. The default is 180, and the range is 10 to 600. 10-600.
The name of a deployments.<environment>.datastores entry that seeds the account from your fixtures for each preview. The account exists only in that database, so its fixture password opens nothing else. SHIP refuses a name that no datastore declares.
