Workflow Run

Origin & evolution

The class-and-instance split that defines a run is old in computing and became explicit in workflow systems as they industrialised. When Apache Airflow formalised pipelines as directed acyclic graphs in 2014, it drew a hard line between the DAG (the definition) and the DAG run (a dated execution with its own task☑️TaskProduct SpecificationA unit of work within a story or epicView reference → states and logs). Business process engines built on BPMN 2.0 make the same distinction between a process model and a process instance.

Two concerns sharpened the run as a first-class object. The first is observability: teams needed to ask "did the Tuesday run finish, and where did it stall?", which only makes sense if the run carries its own state. The second is idempotency. Distributed systems retry failed steps, so a run has to be designed such that re-executing a step produces the same result rather than duplicating it. The run is where retry policy, partial failure, and replay are reasoned about.

How it works in practice

A nightly import-linear-issues template kicks off at 02:00. Run #418 starts, pulls 1,240 issues, and fails at the transform step when one issue has a malformed date. The run's state shows three steps complete, one failed, the rest not started. The retry policy re-runs from the failed step rather than the top, so the 1,240 issues are not fetched twice. On the second attempt the bad record is skipped and logged, the run reaches "succeeded", and it stamps a finish time. Run #419 the next night is a separate object with its own state, even though it shares every line of the template.

Workflow run vs. its neighbours

• Workflow template is the reusable definition; the run is one execution of it. Edit the template and every future run changes; a run, once finished, is a fixed historical record.
• Workflow artifact🗳️Workflow ArtifactWorkflows & AgentsAn output artifact from a workflow runView reference → is something a run produces, a file or report or generated change. The run is the event; the artifact is the durable output left behind, traceable to the run that made it.
• Agent hook🧷Agent HookWorkflows & AgentsA trigger connecting an agent to an eventView reference → is a trigger that fires at a moment during a run, for example "after the build step". The hook reacts to the run's progress; the run is the thing whose lifecycle the hook is listening to.

In the graph

In the Unified Product Graph, a workflow run sits in the automation region as the execution record. Its origin is captured by workflow_template_executed_as_workflow_runWorkflow Templateexecuted asWorkflow Runhierarchy, tying every run back to the definition it enacts. Its outputs are linked through workflow_run_produces_workflow_artifactWorkflow RunproducesWorkflow Artifacthierarchy, so the result is never an orphan. When automated work advances a larger goal, workflow_run_implements_initiativeWorkflow RunimplementsInitiativecross-domain connects the run to that initiative🚀InitiativeStrategyA large coordinated effort to achieve a strategic goalView reference →. Reactive triggers attach with agent_hook_fires_during_workflow_runAgent Hookfires duringWorkflow Runcausal. Modelling runs as their own entities, distinct from templates, is what lets the graph answer historical questions about what executed and what it produced.