Workflow Graphs

Workflow Graphs coordinate several n8v tasks as one visible process. Use them when a job needs parallel work, independent verification, conditional routing, retries, a join, or a human decision.

Each task node is still a normal n8v task. It runs in its own agent environment and branch, appears in your task list, and can be opened from the graph run. The graph owns what starts next and preserves its state across deployments and interruptions.

Create a graph

1. Open Workflow Graphs from the sidebar and select New graph.
2. Choose a bounded pattern: input policy gate, parallel review, verified change, or bounded recovery.
3. Set the repository and base branch, then review the visual preview.
4. Optionally edit the JSON definition. n8v validates every node, edge, limit, repository, and branch before saving.
5. Open the saved graph and select Start run. You can pass an optional JSON object as run input.

Saving an edit creates a new immutable version. A run always stays pinned to the definition, repository, and branch it started with, even when you change the graph later.

Nodes and routes

• Task starts an isolated n8v task. It can retry after a platform-level failure and receives bounded evidence only from direct predecessor tasks.
• Check compares a bounded scalar value in the run input without starting an agent.
• Approval waits for an authenticated approve or reject decision and an optional note.
• Edges route success, failure, approved, rejected, or always outcomes.
• Joins can wait for all incoming routes or continue after any one route.
• Cycles are allowed only with explicit visit and traversal limits.

The current safety limits are four concurrent tasks, 20-way fan-out, 100 planned executions, five visits or retries per node, 200 KB per definition, 20 KB of run input, and 2,000 characters per approval note. Runs expire after seven days, and approvals expire with their run.

Inspect and control a run

The run view shows node status without relying on color, linked tasks, attempts, errors, pending decisions, the pinned version and execution target, and an ordered audit history.

• Pause stops new routing. Tasks already running continue.
• Resume continues routing from persisted state.
• Stop cancels the durable run and its active task nodes.
• Disable graph blocks new manual and automated runs without changing completed history.

If a completion signal is interrupted, a running coordinator normally checks persisted task state again within one minute. Long-lived, waiting, and paused runs use a five-minute safety cadence to preserve durable history for the full seven-day limit. A separate one-minute recovery sweep provides another repair path. Completed nodes are not deliberately rerun.

Start a graph from an automation

Manual and scheduled automations can choose Workflow graph instead of Agent task. Select an enabled graph whose repository and branch match the automation. n8v verifies that match again when the automation runs, so a later graph edit cannot silently redirect scheduled work. Each trigger starts a new durable graph run; it does not create a placeholder task.

GitHub event automations continue to use agent tasks because their event payload and repository context are task-specific.

Definition example

{
  "nodes": [
    {
      "id": "build",
      "name": "Implement",
      "type": "task",
      "prompt": "Implement the requested change and verify it.",
      "maxRuns": 1,
      "retries": 1
    },
    {
      "id": "gate",
      "name": "Release gate",
      "type": "approval",
      "instructions": "Approve only after reviewing the implementation evidence.",
      "maxRuns": 1
    }
  ],
  "edges": [
    { "id": "build-gate", "from": "build", "to": "gate", "on": "success" }
  ],
  "start": ["build"],
  "maxConcurrency": 1
}