Workflow YAML Schema Reference for Shipfox

This page is the authoritative reference for the Shipfox workflow YAML schema. Workflow files live at .shipfox/workflows/*.yml. The schema is strict: unknown keys are rejected everywhere. Use this reference when authoring or debugging workflow files.

Top-level fields

Trigger fields

Job fields

Checkout fields

The optional job checkout block controls the repository credential used for that job. It does not control integration tools.

Step fields

A step is either a run step or an agent step. The kind is determined by which keys are present: run marks a run step; prompt (or any agent field) marks an agent step. The two kinds share one strict object, so unknown keys are always rejected and mixing kinds on one step is a validation error (see Validation rules).

Run step fields

Agent step fields

Agent integration fields

Each entry under an agent step's integrations list selects tools from one workspace integration connection. Selection is validated when the workflow syncs.

The workflow receives the selected operations, not the integration connection credential. Use the smallest selection and repository scope that can complete the task. See Use integration tools for a worked example.

Gate fields

A gate block is optional on both step kinds and must contain at least one of success or on_failure.

This gate fragment belongs on a step whose earlier edit step has a key:

gate:
  success: step.exit_code == 0
  on_failure:
    restart_from: edit
    feedback: Tests are still failing; try again.

Step outputs

A step's outputs: block declares typed outputs: each key maps to a type (string, number, boolean, or json). For json, an object form {type: json, schema: <JSON Schema>} validates the value. Keys must be CEL identifiers (^[a-zA-Z_][a-zA-Z0-9_]*$).

How a step produces the values:

• Run steps append key=value lines to the file named by the SHIPFOX_OUTPUT environment variable. Multi-line values use the heredoc form key<<DELIM ... DELIM.
• Agent steps receive a set_output tool for the declared keys. If the agent finishes without setting a declared output, it is re-prompted a bounded number of times, then the step fails.

Outputs are read on success only, coerced against the declared types, and exposed to later expressions as steps.<key>.outputs.<name>. Job outputs templates lift them to downstream jobs. Size caps live in Limits.

This jobs fragment belongs under an existing workflow's jobs map:

jobs:
  build:
    outputs:
      version: ${{ steps.compile.outputs.version }}
    steps:
      - key: compile
        run: echo "version=$(git describe --tags)" >> "$SHIPFOX_OUTPUT"
        outputs:
          version: string
  release:
    needs: build
    steps:
      - env:
          VERSION: "${{ jobs.build.outputs.version }}"
        run: ./release.sh "$VERSION"

Listening fields

The listening block turns a job into a listening job: after its needs are met, the job activates and fires one execution per matching event batch until it resolves. on and until entries use the same {source, event, filter?, with?} shape as workflow triggers, except config is rejected.

Validation: a listening job must declare at least one resolution source (until, timeout, or max_executions), and batch needs at least one of its three fields.

Environment variables

env maps exist at three levels (workflow, job, and step) and all follow the same rules:

• Run steps only. env is invalid on an agent step, and workflow-level and job-level env is not forwarded to agent steps.
• Nearest scope wins. When the same name is defined at several levels: step env > job env > workflow env.
• POSIX names. Keys must match [A-Za-z_][A-Za-z0-9_]*.
• Values stringify. A value may be a string, number, or boolean; numbers and booleans are stringified before a run is saved.
• No unset syntax. FOO: "" sets an empty string; an empty env: {} block does not remove variables from the runner's process environment.
• Values may interpolate. ${{ }} expressions resolve when their referenced context becomes available; see Expressions.
• Size caps. Each env map holds at most 128 entries and 32 KiB serialized; see Limits.

Constraints table

Validation rules

Full example

This complete workflow requires a Node.js repository, an online ubuntu-latest runner, configured Anthropic credentials, and a GitHub integration connection. Replace github_acme with that integration connection's slug before syncing it.

name: Full example
runner: ubuntu-latest
env:
  NODE_ENV: test
triggers:
  on_demand:
    source: manual
    event: fire
  on_push:
    source: github_acme   # your GitHub integration connection slug
    event: push
jobs:
  test:
    steps:
      - key: install
        run: npm ci
      - run: npm test
        gate:
          success: step.exit_code == 0
          on_failure:
            restart_from: install
  review:
    needs: test
    steps:
      - key: review
        model: claude-opus-4-8
        thinking: high
        prompt: Review the repository and suggest improvements.

Related pages