Skip to main content
Every Shipfox step is one of two kinds: a run step executes a shell command on the runner, or an agent step invokes an AI model. The kind is determined by which keys are present — run marks a run step; prompt (or model, thinking, or provider) marks an agent step. Mixing keys from both kinds on the same step is a validation error.

​
Run step

A run step executes a shell command on the job’s runner. It has access to environment variables from the workflow, job, and step scopes.
​
run
string
required
The shell command to execute. Must be at least one character.
​
name
string
Displayed in the dashboard log. Display-only — a step referenced by restart_from needs a key:, not a name:.
​
env
object
Environment variables for this step. Merged with job-level and workflow-level env; step-level values take the highest precedence. Keys must follow POSIX-style naming ([A-Za-z_][A-Za-z0-9_]*). Values may be strings, numbers, or booleans.
​
key
string
Optional stable identifier for this step. Useful for referencing the step programmatically. Must be at least one character.
​
gate
object
Gate and retry configuration evaluated after the step completes. See Gate block below.
- key: test
  run: npm test
  env:
    CI: "true"
  gate:
    success_if: exit_code == 0
    on_failure:
      restart_from: install   # 'install' is an earlier step's key

​
Agent step

An agent step invokes an AI model with a text prompt. The model reads the repository context and executes the instruction. The recommended pattern is an agent step that produces a change, followed by a run step whose gate judges the result.
​
prompt
string
required
The instruction given to the model. Must be at least one character. Required on any step that also sets model, thinking, or provider.
​
model
string
Model ID to use (e.g., claude-opus-4-8, gpt-5.5-pro). Uses the workspace default if omitted. Model catalog checks are performed at runtime, not at parse time.
​
provider
string
Provider ID for the model (e.g., anthropic, openai, deepseek). Pairing provider with model lets a step target a specific non-default provider/model combination. Uses the workspace default if omitted.
​
thinking
string
Reasoning depth for the model. Controls how many tokens the model spends on internal reasoning before producing a response. Accepted values: off, minimal, low, medium, high, xhigh. Default: high.
​
name
string
Optional step name, displayed in the dashboard log.
​
key
string
Optional stable identifier for this step. Must be at least one character.
​
gate
object
Gate and retry configuration. See Gate block below.
- name: review
  model: claude-opus-4-8
  provider: anthropic
  thinking: high
  prompt: Review the failing test output and fix the code.

​
Gate block

A gate block is optional on both run steps and agent steps. It must contain at least one of success_if or on_failure.
​
success_if
string
A CEL expression evaluated after the step completes. The variable exit_code (integer) is available. Example: exit_code == 0. When omitted, the step’s default exit behaviour applies.
​
on_failure.restart_from
string
The key of an earlier step in the same job to restart from when this step fails. The referenced step must have a key: and appear before the current step in the job’s step list (name: is display-only and cannot be referenced).
​
on_failure.output
string
A message to surface in the run log when this step is considered failed.

​
Constraints table

The following table summarises which fields are valid on each step kind. Mixing fields across kinds on the same step is a validation error.
FieldRun stepAgent step
run✅ Required❌ Not allowed
prompt❌ Not allowed✅ Required
model❌ Not allowed✅ Optional
thinking❌ Not allowed✅ Optional
provider❌ Not allowed✅ Optional
env✅ Optional❌ Not allowed
name✅ Optional✅ Optional
key✅ Optional✅ Optional
gate✅ Optional✅ Optional
The agent: key is reserved for a future step kind. Using it today results in a validation error with a clear message. It is not a valid alias or shorthand for an agent step — use prompt instead.