# Workflows, runs, executions, and attempts (https://www.shipfox.io/docs/understand/workflows-and-runs)

Description: Understand how a workflow file becomes a run, why a run keeps a fixed copy of it, and how reruns, listeners, and feedback loops add history.

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 workflow [#a-run-keeps-a-fixed-copy-of-the-workflow]

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 history [#the-six-levels-of-history]

```text
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 status [#each-level-has-its-own-status]

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 keeps [#what-a-rerun-keeps]

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](https://www.shipfox.io/docs/understand/agent-sessions) into the new attempt.
  Failed, cancelled, and blocked work runs again. 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.

## What cancellation keeps [#what-cancellation-keeps]

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.

Use [Cancel or re-run
work](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/cancel-and-rerun) for the procedure. [Inspect
a run](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/inspect-runs-and-attempts) shows how to move
through these levels in the dashboard.