Workflow YAML reference

Each section lists the fields for one part of a workflow YAML file and highlights that part in an example.

Enable editor autocomplete

Add # yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json as the first line of a workflow file.

Workflow

namestringRequired

Names the workflow.

Use a literal value. Workflow expressions are not allowed.

run_namestring

Names each workflow run. Supports workflow expressions.

triggersRecord<string, Trigger>

Defines the events that start the workflow. Add no more than one manual trigger.

concurrencyConcurrency

Limits each group to one active run and the newest waiting run. See Workflow concurrency groups.

runnerstring | string[]

Selects the default runner for jobs in this workflow. List labels in fallback order. See Runners and execution environments.

envEnvironment

Sets environment variables for run steps in every job.

jobsRecord<string, Job>Required

Defines the jobs that the workflow runs. Add at least one job.

outputsRecord<string, string>

Creates named outputs from job outputs when a run succeeds. An output that cannot be evaluated fails the run.

.shipfox/workflows/workflow.yml

name: Deploy
run_name: Deploy ${{ event.ref }}
triggers:
  push:
    source: github_acme
    event: push
concurrency:
  group: deploy-${{ event.ref }}
runner: shipfox
env:
  NODE_ENV: production
jobs:
  deploy:
    steps:
      - key: deploy
        run: echo "url=https://example.com" >> "$SHIPFOX_OUTPUT"
        outputs:
          url: string
    outputs:
      url: ${{ steps.deploy.outputs.url }}
outputs:
  url: ${{ jobs.deploy.outputs.url }}

`triggers.<trigger_id>`

sourcestringRequired: Selects the slug of an integration connection or a built-in source that starts the workflow. See Integrations for provider sources.
eventstring: Selects the event that starts the workflow. Omit it to accept every event from the source.
filterstring: Starts the workflow only when an event matches this condition. The condition can use event and trigger. manual and cron triggers do not use this field. See Expressions and Contexts.
withRecord<string, value>: Provides values that match or configure the trigger. See each provider's event catalog in Integrations.
secretsRecord<string, value>: Maps trigger input names to secret names in the Shipfox project.
configRecord<string, value>: Configures a built-in trigger source, such as cron. See Schedule workflows.

.shipfox/workflows/triggers.yml

name: Review pull requests
triggers:
  ready:
    source: github_acme
    event: pull_request.ready_for_review
    filter: event.pull_request.base.ref == "main"
    secrets:
      REVIEW_TOKEN: REVIEW_TOKEN
  nightly:
    source: cron
    with:
      suite: full
    config:
      schedule: "0 2 * * *"
jobs:
  review:
    steps:
      - prompt: Review the change and report the main risks.

`concurrency`

groupstringRequired: Names the group. Runs with the same group name wait for each other. Supports workflow expressions. See Contexts.
scopeenumDefault workflow: Chooses whether the group applies to this workflow or every workflow in the project.
workflow
project
cancel_in_progressbooleanDefault false: Set to true to stop the active run when a newer run joins the group.

.shipfox/workflows/concurrency.yml

name: Deploy
concurrency:
  group: deploy-${{ event.ref }}
  scope: project
  cancel_in_progress: true
triggers:
  push:
    source: github_acme
    event: push
jobs:
  deploy:
    steps:
      - run: ./deploy.sh

`env`

<NAME>string | number | boolean

Defines one environment variable. Values support workflow expressions.

Use letters, numbers, and underscores. Start with a letter or underscore.

.shipfox/workflows/env.yml

name: Build
env:
  NODE_ENV: production
  CI: true
jobs:
  build:
    env:
      PORT: 3000
    steps:
      - run: pnpm build
        env:
          LOG_LEVEL: debug

`jobs.<job_id>`

namestring

Names the job.

Use a literal value. Workflow expressions are not allowed.

execution_namestring

Sets the name of each job execution. Supports workflow expressions.

needsstring | string[]

Lists the jobs that must finish before this job starts.

ifstring

Runs this job only when the condition is true. See Conditionals.

runnerstring | string[]

Selects the runner for this job. List labels in fallback order. See Runners and execution environments.

execution_timeoutstring

Stops one job execution after this duration.

envEnvironment

Sets environment variables for every run step in this job.

checkoutJobCheckout

Configures repository permissions and saved credentials for this job. Set to false to skip checkout.

listeningListening

Keeps the job open for matching events. Set until, timeout, or max_executions to end it. See Listening jobs.

stepsStep[]Required

Lists the steps that this job runs in order.

Add at least one item.

successstring

Marks the job as successful when the condition returns true. See Expressions and Contexts.

outputsRecord<string, string>

Creates named outputs from values produced by this job's steps. A later job must list this job in needs before it can use them.

.shipfox/workflows/jobs.yml

name: Build and release
jobs:
  build:
    name: Build
    runner: shipfox
    execution_timeout: 30m
    env:
      NODE_ENV: production
    steps:
      - key: pkg
        run: printf 'version=%s\n' "$(cat VERSION)" >> "$SHIPFOX_OUTPUT"
        outputs:
          version: string
    outputs:
      version: ${{ steps.pkg.outputs.version }}
  release:
    execution_name: Release ${{ jobs.build.outputs.version }}
    needs: build
    if: ${{ event.ref == "refs/heads/main" }}
    steps:
      - key: publish
        run: ./publish.sh "${{ jobs.build.outputs.version }}"
    success: ${{ steps.publish.status == "succeeded" }}

`jobs.<job_id>.checkout`

permissionsCheckoutPermissions: Sets the repository permissions for this checkout.
persist-credentialsboolean: Keeps checkout credentials available to later run steps.

.shipfox/workflows/job-checkout.yml

name: Push a fix
jobs:
  fix:
    checkout:
      permissions:
        contents: write
      persist-credentials: true
    steps:
      - prompt: Fix the failing test and commit the change.
      - run: git push origin HEAD

`jobs.<job_id>.listening`

onTrigger[]Required

Selects the events to listen for.

Add at least one item.

untilTrigger[]

Stops listening when one of these events arrives.

Add at least one item.

timeoutstring

Stops listening after this duration.

max_executionsinteger

Stops listening after this many job executions.

Use a number greater than 0.

batchListeningBatch

Groups matching events before the job processes them. Set debounce, max_size, or max_wait.

on_resolveenum

Chooses what Shipfox does when listening ends. finish lets the current execution finish. cancel stops it.

finish
cancel

.shipfox/workflows/listening.yml

name: Answer review comments
jobs:
  answer:
    listening:
      on:
        - source: github_acme
          event: pull_request_review_comment.created
      until:
        - source: github_acme
          event: pull_request.closed
      timeout: 8h
      max_executions: 10
      on_resolve: finish
    steps:
      - prompt: Answer the review comment in the step log.

`jobs.<job_id>.listening.batch`

debouncestring

Waits for this quiet period before processing a batch.

max_sizeinteger

Limits each batch to this number of events.

Use a number greater than 0.

max_waitstring

Processes a partial batch after this duration.

.shipfox/workflows/listening-batch.yml

name: Summarize review comments
jobs:
  summarize:
    listening:
      on:
        - source: github_acme
          event: pull_request_review_comment.created
      timeout: 8h
      batch:
        debounce: 30s
        max_size: 5
        max_wait: 2m
    steps:
      - prompt: Summarize the comments in this batch.

`jobs.<job_id>.steps[*]`

keystring: Gives the step an identifier that other fields can use.
namestring: Sets the name shown for the step.
ifstring: Runs this step only when the condition is true. See Conditionals.
gateGate: Checks the step result and can restart earlier steps. Set success, on_failure, or both. See Feedback loops.
outputsRecord<string, Output>: Defines values that later steps can use.

.shipfox/workflows/steps.yml

name: Test
jobs:
  test:
    steps:
      - key: unit
        name: Unit tests
        if: ${{ event.pull_request.draft == false }}
        run: pnpm test
        gate:
          success: step.exit_code == 0

`steps[*].gate`

successstring: Marks the step as successful when the condition returns true. See Check and restart are separate.
on_failureGateFailure: Restarts the job from an earlier step when the gate fails. See Feedback loops.

.shipfox/workflows/gate.yml

name: Fix until tests pass
jobs:
  fix:
    steps:
      - key: fix
        prompt: Fix the failing test.
      - key: test
        run: pnpm test
        gate:
          success: step.exit_code == 0
          on_failure:
            restart_from: fix

`steps[*].gate.on_failure`

restart_fromstringRequired: Selects the earlier step where the job restarts after the gate fails.
feedbackstring: Provides text that the repeated step can read after the gate fails.

.shipfox/workflows/gate-failure.yml

name: Fix until tests pass
jobs:
  fix:
    steps:
      - key: fix
        prompt: |
          Fix the failing test.
          Feedback: ${{ step.is_retry ? step.restart.feedback : "No previous feedback." }}
          Test log: ${{ has(step.restart) && has(step.restart.from.log_path) ? step.restart.from.log_path : "None." }}
      - key: test
        run: pnpm test
        gate:
          success: step.exit_code == 0
          on_failure:
            restart_from: fix
            feedback: The tests still fail. Reproduce the failure first.

`steps[*].outputs`

<output_name>string | number | boolean | json | {type: string | number | boolean} | {type: json; schema?: value}: Defines an output from the step. Set its type directly, for example sha: string, or use an object with type. Only json outputs can include schema. Without schema, a json output can contain any JSON value.

.shipfox/workflows/step-outputs.yml

name: Publish outputs
jobs:
  build:
    steps:
      - key: version
        run: printf 'sha=%s\ncount=3\n' "$(git rev-parse HEAD)" >> "$SHIPFOX_OUTPUT"
        outputs:
          sha: string
          count: number
          report:
            type: json
            schema:
              type: object

`steps[*]` run step

Accepts the shared step fields plus:

Run step

runstringRequired: Runs a shell command. Pass workflow values as command arguments, such as deploy "$TARGET". Do not send them to commands such as eval or sh -c.
working_directorystring: Sets the folder where the command runs. The path is relative to the job workspace.
envEnvironment: Sets environment variables for this run step.

.shipfox/workflows/run-step.yml

name: Build
jobs:
  build:
    steps:
      - key: compile
        run: |
          pnpm install --frozen-lockfile
          pnpm build
        working_directory: apps/api
        env:
          NODE_ENV: production

`steps[*]` agent step

Accepts the shared step fields plus:

Agent step

promptstringRequired

Gives the agent its instructions.

harnessenum

Selects the agent runtime. Shipfox uses the workspace default harness, or pi if no default exists. See Agent harness.

pi
claude

providerstring

Selects the model provider for this step. See Model providers.

modelstring

Selects the model that the agent uses.

thinkingenum | expression

Sets agent reasoning. default requests the provider default without workspace or deployment overrides. Omitting this field uses configured defaults or xhigh. Available values depend on the harness. Supports workflow expressions. See Model providers.

off
minimal
low
medium
high
xhigh
max
default

toolsstring[]

Gives the agent the listed built-in tools.

Add at least one item.

integrationsIntegration[]

Adds tools from integration connections to this agent step. See integrations and tools.

Add at least one item.

tool_surfaceenum

Integration tool surface for an agent step. Strict direct tools are the default; discovery retains the generic mcp proxy.

strict-direct
discovery

sessionstring | Session

Continues an agent conversation across steps in one workflow run. See Agent sessions.

Use letters, numbers, dots, underscores, or hyphens. Start with a letter or number. Use at most 128 characters.

.shipfox/workflows/agent-step.yml

name: Review
jobs:
  review:
    steps:
      - key: review
        prompt: Review the change and report the main risks.
        harness: claude
        provider: anthropic
        model: claude-sonnet-5
        thinking: high
        tools: [read_file]
        integrations:
          - include: [pull_request_read]
        session: review

`steps[].integrations[]`

connectionstring

Selects an integration connection by its slug.

includestring[]Required

Selects tools for the agent. See Integrations for each provider's selectors.

Add at least one item.

excludestring[]

Removes tools from the include selection.

Add at least one item.

allow_writeboolean

Set to true to let the agent use tools that can change external data. Otherwise, the agent receives read-only tools.

.shipfox/workflows/agent-integrations.yml

name: Triage issues
jobs:
  triage:
    steps:
      - prompt: Label the issue and post a short triage comment.
        integrations:
          - connection: github_acme
            include: [issue_read, issue_write]
            exclude: [issue_write.update]
            allow_write: true

`steps[*].session`

keystringRequired

Names the session. Supports a ${{ }} expression.

Use letters, numbers, dots, underscores, or hyphens. Start with a letter or number. Use at most 128 characters.

modeenumDefault resume

Chooses how to continue the session. resume continues and updates it. fork reads a snapshot without updating it.

resume
fork

.shipfox/workflows/agent-session.yml

name: Review
jobs:
  review:
    steps:
      - key: draft
        prompt: Review the diff and note the main risks.
        session: review
      - key: summary
        prompt: Summarize your findings for the author.
        session:
          key: review
          mode: fork

`steps[*]` tool step

Tool step

toolstringRequired

Calls an integration tool by its id. Use a standalone tool or a family method such as family.method. See Call an integration tool for an example.

Use a literal value. Workflow expressions are not allowed.

connectionstring

Selects an integration connection by its slug. If omitted, Shipfox uses the source integration connection of the project.

Use a literal value. Workflow expressions are not allowed.

withRecord<string, value>

Provides input values to the tool. The tool defines the accepted fields. String values support workflow expressions. See Context availability.

.shipfox/workflows/tool-step.yml

name: Notify
jobs:
  notify:
    steps:
      - key: message
        tool: send_message
        connection: slack_acme
        with:
          channel_id: C0ABC12345
          message: Run ${{ run.number }} started.
        outputs:
          ts: ${{ result.ts }}

`steps[*].outputs` tool step

Tool step

<output_name>string: Creates an output from the tool response or a workflow variable. Use one workflow expression. Later steps can read the full response from steps.<key>.outputs.result.

.shipfox/workflows/tool-step-outputs.yml

name: Notify
jobs:
  notify:
    steps:
      - key: message
        tool: send_message
        connection: slack_acme
        with:
          channel_id: C0ABC12345
          message: Run ${{ run.number }} started.
        outputs:
          ts: ${{ result.ts }}
          channel: ${{ result.channel }}
      - env:
          MESSAGE_TS: ${{ steps.message.outputs.ts }}
        run: printf 'Posted %s\n' "$MESSAGE_TS"

`steps[*]` checkout step

Accepts the shared step fields plus:

Checkout step

checkoutCheckoutRequired: Checks out a repository for this step.

.shipfox/workflows/checkout-step.yml

name: Compare branches
jobs:
  compare:
    steps:
      - key: base
        checkout:
          ref: main
          path: base
      - run: diff -rq base . || true

`steps[*].checkout`

projectstring

Checks out the repository from this Shipfox project. Do not use it with connection or repository.

connectionstring

Selects the integration connection that can access the repository. Use it with repository.

repositorystring

Names the repository to check out. Use owner/name or a bare repository name.

refstring

Selects the branch, tag, or commit to check out.

pathstring

Sets the destination folder under the job workspace.

fetch-depthinteger

Sets how many commits to fetch. Use 0 for the full history.

Use 0 or a larger number.

forceboolean

Allows checkout to replace existing content at the destination.

permissionsCheckoutPermissions

Sets the repository permissions for this checkout.

persist-credentialsboolean

Keeps checkout credentials available to later run steps.

.shipfox/workflows/checkout.yml

name: Check out a second repository
jobs:
  docs:
    steps:
      - checkout:
          connection: github_acme
          repository: acme/docs
          ref: main
          path: docs
          fetch-depth: 1
          force: true
          permissions:
            contents: read
          persist-credentials: false
      - run: ls docs

`steps[*].checkout.permissions`

contentsenum: Sets read or write access to the repository contents.
read
write

.shipfox/workflows/checkout-permissions.yml

name: Push docs changes
jobs:
  docs:
    steps:
      - checkout:
          connection: github_acme
          repository: acme/docs
          path: docs
          permissions:
            contents: write
          persist-credentials: true
      - run: git -C docs push origin HEAD

Edit this page on GitHub

Workflow YAML reference

Workflow

`triggers.<trigger_id>`

`concurrency`

`env`

`jobs.<job_id>`

`jobs.<job_id>.checkout`

`jobs.<job_id>.listening`

`jobs.<job_id>.listening.batch`

`jobs.<job_id>.steps[*]`

`steps[*].gate`

`steps[*].gate.on_failure`

`steps[*].outputs`

`steps[*]` run step

`steps[*]` agent step

`steps[].integrations[]`

`steps[*].session`

`steps[*]` tool step

`steps[*].outputs` tool step

`steps[*]` checkout step

`steps[*].checkout`

`steps[*].checkout.permissions`

Contexts

Expressions

Model Providers

Limits

On this page