Workflow YAML reference

Look up supported fields, accepted values, and nested blocks while writing a workflow.

Top-level fields

Workflow and job names

Workflow and job names use separate static and dynamic fields.

Static names

Workflow name and job name values are literal labels. A job name is optional. Add one when the job key is not a useful label. The job key is the fallback when no job name is set.

Interpolation in a static name is invalid. Use the matching dynamic field:

Workflow name must be literal. Move runtime interpolation to run_name.
Job name must be literal. Move runtime interpolation to execution_name.

Dynamic run names

run_name resolves when Shipfox creates a workflow run. It can use trigger metadata, trigger event data, workflow inputs, referenced workflow variables, and stable run facts that already exist at creation time.

The allocated run.number is one of those run facts. It is a positive, sequential number scoped to the workflow definition. Use it in a dynamic field when the field can read the run context.

It cannot use job, execution, step, or job-output values that do not exist when the run is created. A rerun keeps the original resolved run name.

Dynamic execution names

execution_name resolves when Shipfox creates a job execution. It can use run context, trigger data, inputs, referenced variables, stable job facts, the execution sequence, listener events, and prior executions.

It cannot use the current execution name, future executions, step results, or job outputs that do not exist at execution creation.

Listening jobs resolve execution_name separately for each execution. The template can therefore include the event batch or execution sequence.

Fallbacks and reruns

Dynamic names are optional and affect display labels only. If a dynamic field is omitted or resolves to an empty value, Shipfox uses the matching static fallback. A runtime resolution failure also uses that fallback and records a diagnostic without changing execution status.

Dynamic-name expressions that use unavailable context or invalid syntax are definition validation errors. Rerunning a workflow keeps its resolved run name. Rerunning a job execution keeps its resolved execution name.

Run number

run.number is a display label for the current run. It starts at 1 for each workflow definition and increases for later runs of that definition. It is not a URL or API identifier. Run routes continue to use the run UUID.

For example, a job execution can include the number in its display name:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Deploy
jobs:
  deploy:
    execution_name: 'Deploy #${{ run.number }}'
    steps:
      - run: ./deploy.sh

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Pull request review
run_name: 'Review PR #${{ event.pull_request.number }}'

jobs:
  reviews:
    name: Process review
    execution_name: Review batch ${{ execution.index }}
    listening:
      on:
        - source: github
          event: pull_request_review
    steps:
      - prompt: Summarize ${{ execution.events[0].data.body }}

Trigger fields

Job fields

Job outputs values are templates. A value that contains exactly one expression preserves its inferred non-string type, including arrays and objects. An expression without an inferred type resolves to a string. Mixed literal and expression templates also resolve to strings. A downstream job must declare a direct needs edge before it reads the output.

Job checkout fields

The job-level checkout block supports repository permissions and credential persistence. checkout: false is accepted by the document schema but is not supported by the workflow model yet.

Checkout fields

These fields apply to an explicit checkout step.

Checkout permissions fields

These permissions apply to both job-level checkout and explicit checkout steps.

Step fields

Each step is either a run step, an agent step, or a checkout step. The schema rejects unknown fields and invalid field combinations.

Run step fields

A ${{ }} value in run reaches the command as a quoted shell variable, so the shell reads it as text and not as part of the command.

Checkout step fields

Agent step fields

Agent integration fields

Gate fields

A gate must define success, on_failure, or both.

Gate failure fields

Step outputs

Each output declaration can be its type directly (for example, sha: string) or an object with required type. Only json declarations can include schema.

Listening fields

Listening batch fields

A batch must set at least one of debounce, max_size, or max_wait.

Environment variables

Related pages