Shipfox

Workflow YAML reference

Define when Shipfox runs and what each workflow does.

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.

run_afterenum

Picks when this job runs relative to the jobs in needs: success (default) needs every job to succeed, failure needs at least one job to fail, always runs whatever their status. The if is checked after run_after passes.

  • success
  • failure
  • always
runnerstring | string[]

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

containerstring | JobContainer

Runs this job in a Docker container. Set a string for the image, or an object for the image and its settings.

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 the project checkout at the job root. Set to false to skip that 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 of this job. Each step starts after the step before it ends, unless that step runs in the background or in a parallel block.

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>.container

imagestringRequired

Names the Docker image the job runs in. The ENTRYPOINT and CMD of the image do not run. Supports workflow expressions, but cannot read secrets.

credentials{username: string; password: string}

Signs in to a private registry before the runner pulls the image.

envEnvironment

Sets environment variables for every process in the container.

optionsstring

Passes extra flags to docker create, as written. Do not set --network or --entrypoint: the runner sets them. Supports workflow expressions, but cannot read secrets.

docker_socketbooleanDefault true

Mounts the Docker socket of the runner into the container. Defaults to true.

.shipfox/workflows/job-container.yml
name: Lint with the toolbox image
jobs:
  lint:
    runner: shipfox
    container:
      image: ghcr.io/acme/toolbox:2026.10
      credentials:
        username: acme-bot
        password: ${{ secrets.GHCR_TOKEN }}
      env:
        LICENSE_KEY: ${{ secrets.TOOLBOX_LICENSE }}
      options: --cpus 4 --memory 12g
      docker_socket: false
    steps:
      - run: acme-lint --strict

See Run a job in a container.

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.

run_afterenum

Picks when this step runs relative to earlier steps in the job: success (default) skips it after a failed step, failure runs it only after a failed step, always runs it either way. The if is checked after run_after passes.

  • success
  • failure
  • always
continue_on_errorboolean

Lets the job go on as if this step succeeded when it fails. The step still ends failed, but its failure does not count for run_after or for the job result. Gate restarts run first. It does not cover a step that cannot start or a job that times out.

backgroundboolean

Starts the step and moves on to the next step without waiting. The step needs a key. Later steps read its results after a wait that joins it.

waitstring | string[]

Blocks until the listed background steps finish. Give one step key or a list. A wait step accepts only name.

wait_allnull | boolean

Blocks until every background step that is still running finishes. Write wait_all: or wait_all: true. A wait step accepts only name.

cancelstring | string[]

Stops the listed background steps without waiting for them to finish. Give one step key or a list. A cancel step accepts only name.

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.

exporttrue | string[]

Promotes outputs of this step to job outputs of the same name. Use true for every declared output, or list the output names. The step needs a key. Checkout steps do not support it.

.shipfox/workflows/steps.yml
name: Test
jobs:
  test:
    steps:
      - key: db
        background: true
        run: docker run --rm --name pg -p 5432:5432 -e POSTGRES_PASSWORD=pg postgres:17
      - key: unit
        name: Unit tests
        if: ${{ event.pull_request.draft == false }}
        run: pnpm test
        gate:
          success: step.exit_code == 0
        outputs:
          coverage: number
        export: true
      - cancel: db

steps[*].gate

successstring

Marks the step as successful when the condition returns true. See Check and restart are separate.

on_failureGateFailure | GateFailure[]

Restarts the job from an earlier step when the gate fails. Give one rule, or a list of rules where the first rule that applies restarts the job. 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

ifstring

Selects this rule when the condition returns true. A rule with no if always applies, so only the last rule can omit it. The condition reads the same context as success, including step.outputs. Use has() before you read an output the step may not set. When no rule applies, the job fails with the error of the step.

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. Supports workflow expressions.

max_attemptsintegerDefault 5

Maximum number of executions of the gating step, including the first execution. Accepts integers from 1 through 1,000. Omit to use five attempts. There is no unlimited value.

Use 1 or a larger number. Use 1000 or a smaller number.

.shipfox/workflows/gate-failure.yml
name: Fix until tests pass
jobs:
  fix:
    steps:
      - key: install
        run: pnpm install
      - key: fix
        prompt: Fix the failing test.
      - key: test
        run: ./scripts/test.sh # writes failure-kind.txt when the tests fail
        outputs:
          failure_kind:
            type: string
            from_file: failure-kind.txt
        gate:
          on_failure:
            - if: has(step.outputs.failure_kind) && step.outputs.failure_kind == "assertion"
              restart_from: fix
              feedback: The tests still fail. Reproduce the failure first.
            - if: has(step.outputs.failure_kind) && step.outputs.failure_kind == "flaky"
              restart_from: install
              max_attempts: 2

steps[*].outputs

<output_name>string | number | boolean | json | {type: string | number | boolean; default?: value; from_file?: string; from_stdout?: true} | {type: json; schema?: value; default?: value; from_file?: string; from_stdout?: true}

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. Run and agent steps can add default, which later steps read when the step has no value for the output, for example when it is skipped. The default must match the type and schema. Only run steps support from_file and from_stdout; agent and checkout steps reject them. from_file reads the output from a file after the command exits, and from_stdout reads it from standard output. A file path is relative to the step working directory and must stay inside the job workspace. A missing file leaves the output unset. Standard output and each file are limited to 64 KiB, and one trailing newline is removed. An output uses from_file or from_stdout, not both, and a step has at most one from_stdout output.

.shipfox/workflows/step-outputs.yml
name: Publish outputs
jobs:
  build:
    steps:
      - key: revision
        run: git rev-parse HEAD
        outputs:
          commit:
            type: string
            from_stdout: true
      - 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
          outcome:
            type: string
            default: none
      - key: package
        run: git diff --cached --binary > .git/shipfox-repair.patch
        outputs:
          patch:
            type: string
            from_file: .git/shipfox-repair.patch

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
promptstring | PromptPart[]Required

Gives the agent its instructions. Use a string, or a list of parts that Shipfox joins with a blank line. A part is a string or a file reference.

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.

mcp_serversRecord<string, McpServer>

Gives the agent the tools of these MCP servers as <name>__<tool>. The runner starts each command server for the step and connects to each url server. Each key is a server name: a lowercase letter, then lowercase letters, numbers, and single underscores, with at most 20 characters. See Use your own MCP server.

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.

repository_contextboolean | string | RepositoryContextDefault true

Controls the repository instructions and skills that the agent reads. Set to false to turn both off, or set instructions and skills separately. See Coding agents.

.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.

.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]

steps[*].mcp_servers.<name>

commandstring

Names the program that starts the server. It runs without a shell. Set command or url, not both.

Use a literal value. Workflow expressions are not allowed.

argsstring[]

Passes these arguments to command. Workflow expressions are not allowed; use env for values.

envEnvironment

Sets environment variables for the command server. Values support workflow expressions, including secrets.

urlstring

Connects to a server that you run, over Streamable HTTP. An http or https URL that the runner can reach. Set command or url, not both.

Use a literal value. Workflow expressions are not allowed.

headersRecord<string, string>

Sends these HTTP headers to the url server with every request. Values support workflow expressions, including secrets.

includestring[]

Lists the tools to give the agent, named as the server lists them. Defaults to every tool.

Add at least one item.

.shipfox/workflows/agent-mcp-servers.yml
name: Investigate slow queries
jobs:
  investigate:
    steps:
      - prompt: Find the slowest queries on the orders collection.
        mcp_servers:
          mongodb:
            command: npx
            args: [-y, mongodb-mcp-server@1.2.0]
            env:
              MDB_MCP_CONNECTION_STRING: ${{ secrets.MONGO_URI }}
              MDB_MCP_READ_ONLY: "true"
            include: [find, aggregate, list-collections, explain]
          internal_docs:
            url: http://127.0.0.1:3000/mcp
            headers:
              Authorization: Bearer ${{ secrets.DOCS_MCP_TOKEN }}

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[*].repository_context

instructionsboolean | stringDefault true

Reads AGENTS.md or CLAUDE.md from the runner home directory and from the repository root down to the working directory. Supports a ${{ }} expression.

skillsboolean | string | string[]Default true

Loads skills from the skill directories of mainstream coding agents, such as .agents/skills and .claude/skills, in the repository and in the runner home directory. Use true, false, a ${{ }} expression, or a list of skill names.

.shipfox/workflows/agent-repository-context.yml
name: Review
jobs:
  review:
    steps:
      - prompt: Review the pull request and list the main risks.
        repository_context:
          instructions: true
          skills: [code-review]

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. Set a non-root path to keep the project checkout at the job root.

.shipfox/workflows/checkout-step.yml
name: Compare branches
jobs:
  compare:
    steps:
      - key: base
        checkout:
          ref: main
          path: base
      - run: |
          diff -rq --exclude=.git base . | grep -vxF 'Only in .: 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 root. Required unless this checkout owns the job root.

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

steps[*] parallel block

A parallel block is an item of steps that holds only the parallel field. Each item of its list is a step with the shared step fields.

parallelStep[]Required

Runs the listed steps at the same time, then waits for all of them. It is shorthand for marking each step background: true and adding a wait that names exactly those steps. A step needs no key, but without one its outputs are not readable.

Add at least 2 items.

.shipfox/workflows/parallel.yml
name: Test
jobs:
  test:
    steps:
      - run: npm ci
      - parallel:
          - key: lint
            run: npm run lint
          - key: unit
            continue_on_error: true
            run: npm test
      - run: npm run build

Concurrent step rules

These rules cover background, wait, wait_all, cancel, and parallel. Sync rejects a workflow that breaks one of them.

RuleApplies to
Needs a key.A step with background: true.
Is a run, action, agent, or tool step. A checkout step cannot run in the background.A step with background: true.
Cannot have a gate.A background step and a step of a parallel block.
Accepts only name. It cannot set if, run_after, or continue_on_error.A wait, wait_all, or cancel step.
Names a background step that exists and is still running at that point.A wait or cancel step.
Cannot run while a background step may still run. Add wait_all before it.A checkout step.
Lists at least two steps and takes no other field. Blocks do not nest.A parallel block.
Is not a checkout, wait, wait_all, cancel, or parallel step, and does not set background or gate.A step of a parallel block.
Cannot go back past a background step that may still be running. Cannot name a step in the middle of a parallel block.gate.on_failure.restart_from.
Cannot read steps.<key> of a background step before a wait joins it.An expression.
Cannot use the same key as another step that can run at the same time, unless both steps use mode: fork.An agent session.

A wait or wait_all step always runs. It fails when a step it waits for failed without continue_on_error. wait_all waits for every background step started earlier that no wait joined and no cancel stopped.

Without name, the run page labels these steps by their keys:

StepLabel
wait: [security, perf]Wait for security, perf
wait_all:Wait for background steps
cancel: dbCancel db
The wait at the end of a parallel blockWait for parallel steps

Jobs and steps explains how these steps run.

Agent file

A file in .shipfox/agents/ configures one project agent. The file name without its extension is the agent key, so a file declares no key, and a nested file is an error. shippy.yaml adds to the built-in agent, and every field in it is optional. Any other file is a custom agent, which needs description and instructions. Sync checks each agent file on its own. An invalid file keeps the agent's last valid version, reports the error, and never blocks the workflows.

integrations uses the selectors of an agent step. Sync rejects a file that selects an unknown tool. Shipfox records a write call before it runs. If the call stops after it starts and before its result is stored, a retry does not run it again. The agent gets the result unknown and reads the current state before it tries again.

namestring

Sets the display name of the agent. Without it, the agent shows its key, the file name without the extension. The name never identifies the agent.

Use a literal value. Workflow expressions are not allowed.

descriptionstring

Describes what the agent is for. Users read it when they pick an agent. Required for a custom agent.

instructionsstring | PromptPart[]

Gives the agent its instructions. Use a string, or a list of parts that Shipfox joins with a blank line. A part is a string or a file reference. In shippy.yaml the instructions add to the built-in prompt. Required for a custom agent, where they are the whole prompt.

modelstring

Selects the model that the agent uses. Without it, the workspace default applies.

providerstring

Selects the model provider for the agent. See Model providers.

thinkingenum

Sets agent reasoning. default requests the provider default without workspace or deployment overrides. Omitting this field uses configured defaults or xhigh.

  • off
  • minimal
  • low
  • medium
  • high
  • xhigh
  • max
  • default
integrationsIntegration[]

Adds tools from integration connections to the agent. See integrations and tools.

Add at least one item.

onRule[]

Declares the requests from Slack or Linear that the agent claims. When several rules match, a custom agent wins over a Shippy, and the rule added first wins within each.

.shipfox/agents/reviewer.yaml
name: Code reviewer
description: Reviews pull requests in this project and reports the main risks.
instructions:
  - Review the change like a senior engineer on this team.
  - file: ./.shipfox/prompts/review-rules.md
model: claude-sonnet-5
provider: anthropic
thinking: high
integrations:
  - include: [pull_request_read]
on:
  - source: slack_acme
    filter: request.channel_id == "C04PAYMENTS" || request.viewing_channel_id == "C04PAYMENTS"
  - source: linear_acme
    filter: "'payments' in request.labels"

Agent rules

An on rule declares which requests the agent claims. A request is a message that starts a conversation, such as a mention in a Slack channel or a Linear agent session. One agent answers each conversation. When several rules match a new request, a custom agent wins over a Shippy, and within each group the rule that was added first wins. A request that no rule matches goes to the Shippy of the workspace's default project. Replies in a thread stay with the agent that answered first, even after a rule changes.

source is the slug of an integration connection that lets people talk to agents, such as slack_acme or linear_acme. Use the slug of your own connection. A rule has no event, with, secrets, or config, because only requests can match. filter is a condition like a workflow trigger filter. It reads request, where the request was made, and event, the raw payload. Sync rejects a filter on a field that the provider does not set for request, and a filter longer than 2,000 bytes. See Limits. A rule that sync rejects leaves the agent on its last valid version.

sourcestringRequired

Selects the slug of the integration connection whose requests this rule covers, such as slack_acme or linear_acme. Use the slug of your own connection. The integration must let people talk to agents.

filterstring

Narrows the rule to requests that match this condition. The condition can use request, where the request was made, and event, the raw payload. Without it, the rule covers every request from the source. See Expressions.

.shipfox/agents/reviewer.yaml
name: Code reviewer
description: Reviews pull requests in this project and reports the main risks.
instructions:
  - Review the change like a senior engineer on this team.
  - file: ./.shipfox/prompts/review-rules.md
model: claude-sonnet-5
provider: anthropic
thinking: high
integrations:
  - include: [pull_request_read]
on:
  - source: slack_acme
    filter: request.channel_id == "C04PAYMENTS" || request.viewing_channel_id == "C04PAYMENTS"
  - source: linear_acme
    filter: "'payments' in request.labels"
Was this page helpful?
Edit this page on GitHub

On this page