Workflows, runs, executions, and attempts

A workflow is a file in the repository that describes work to do. A run is the record Shipfox creates when one event or manual start uses that workflow. The workflow file can change over time. The run must stay an accurate record of what it used.

That need for a stable record is why Shipfox keeps more than one level of history.

A run keeps a fixed copy of the workflowCopy Anchor Link

Shipfox syncs workflow files from the repository into stored definitions. A successful sync changes what future runs use. It doesn't start work, and it doesn't change an active or finished run.

When a trigger starts a run, Shipfox copies the workflow into a run attempt. The attempt keeps the parsed job graph and the agent tool selection for that work. The run also keeps its starting event, its inputs, and the source snapshot.

This has two useful results.

• A workflow edit can't change the meaning of work that is already running.
• A later investigation can compare the saved source with the jobs, tools, and outputs that actually ran.

Start a new run when the work must use a newly synced definition. A rerun keeps the original copy.

The six levels of historyCopy Anchor Link

run
`-- run attempt
    `-- job
        `-- job execution
            `-- step
                `-- step attempt

A simple run has one item at each level. The extra levels appear when work repeats.

• Run attempt: a rerun adds another attempt under the same run.
• Job execution: a listening job adds an execution for each matching event batch.
• Step attempt: a feedback loop adds an attempt when a gate restarts an earlier step.

These three are different kinds of repetition. A rerun repeats the run plan. A listening execution handles new outside input. A step attempt revises work after a check failed.

Each level has its own statusCopy Anchor Link

The run shows the overall state. Each attempt, job, execution, and step keeps its own state and history. A mixed result stays readable: one job succeeded, a listener still waits, and another step is on its second attempt.

A finished run shows whether its current attempt succeeded, failed, or stopped after a cancellation. Earlier attempts and their logs stay available. The dashboard can therefore show both the current result and the path that led to it.

What a rerun keepsCopy Anchor Link

A rerun keeps the same run, starting event, inputs, source snapshot, and workflow copy. It creates a new run attempt with new jobs and executions.

The rerun choice decides what moves into the new attempt.

• Re-run failed jobs carries successful jobs, their published outputs, and named agent sessions into the new attempt. Failed, cancelled, and blocked work runs again, along with every job that needs it, even if that job succeeded. Rerun steps can continue the conversations from the source attempt.
• Re-run all jobs starts every job and named agent session from scratch.

Carried outputs let later jobs use a successful result without rebuilding it. The old job's files and process environment don't move to the new attempt.

Start a new run instead when the event, the inputs, or the workflow definition must change.

How runs and executions are namedCopy Anchor Link

A workflow and a job each have a static name and a dynamic name. The static name is a literal label. The dynamic name is a template that Shipfox resolves when it creates the run or the execution.

A job name is optional. Add one when the job key is not a useful label; the key is the fallback. An expression in a static name is a validation error:

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

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, such as run.number. It cannot use job, execution, step, or job-output values that do not exist yet.

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 yet. A listening job resolves it separately for each execution, so the template can include the event batch or the execution sequence.

Dynamic names affect display labels only. If a dynamic field is omitted or resolves to an empty value, Shipfox uses the static fallback: the workflow name for a run, and the job name or the job key for an execution. A runtime resolution failure also uses that fallback and records a diagnostic without changing execution status. A dynamic-name expression that uses unavailable context or invalid syntax is a definition validation error.

A rerun keeps the original resolved run name. A rerun of a job execution keeps its resolved execution name.

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 use the run UUID.

# 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 }}

What cancellation keepsCopy Anchor Link

Cancellation stops the active attempt. Shipfox stops unfinished work and marks the affected levels as cancelled. Completed logs, outputs, and earlier attempts stay available.

Cancellation therefore differs from deleting a record. It changes the outcome of active work and keeps the evidence needed to understand it.

Inspect a run shows how to move through these levels in the dashboard.