Task Graphs and Branching

Bosun tasks can now be expressed as graphs so you can branch, merge, and conditionally skip steps without writing imperative control flow. The manifest still lists the individual steps, but you describe how they connect by declaring start and end nodes plus the transitions between them.

Graph Manifest Structure

A graph manifest extends the familiar task format with three top-level fields:

• starts_with: the id of the first step Bosun should execute.
• ends_with: the id of the terminal step. When Bosun reaches this node, the workflow exits.
• edges: an array of directed connections between step IDs. Each edge optionally declares an on condition.

Every step in a graph needs a stable id. If you omit them, Bosun generates defaults such as step-1, but naming them yourself makes edges easier to read.

name: update-dependencies
description: Run tests, try an autofix, and only open a PR if everything passes.

steps:
  - id: run-tests
    name: Run test suite
    agent:
      extends: Coding
      instructions: "Execute npm test and summarise the result."

  - id: try-fix
    name: Attempt automatic fix
    agent:
      extends: Coding
      instructions: "Apply straightforward fixes for the failing tests."

  - id: open-pr
    name: Prepare pull request
    agent:
      extends: pull_request

starts_with: run-tests
ends_with: open-pr

edges:
  - from: run-tests
    to: try-fix
    on: failure
  - from: run-tests
    to: open-pr
    on: success
  - from: try-fix
    to: run-tests
    on: success

Bosun continues to support sequential manifests that omit these fields. When you provide only a list of steps, the platform automatically infers a simple success chain. Add starts_with, ends_with, and edges when you need finer control.

Edge Conditions

Transitions default to success when no on value is set. You can also choose:

• failure: trigger when the source step reports a failure.
• A custom expression: Bosun renders the string as a template in the current task context and treats any non-empty, non-false/0 value as truthy.

For example, you can branch on the contents of a previous step output:

  - from: validate-report
    to: notify-team
    on: '{{ outputs.validate-report.result == "changes_required" }}'

Keep expressions short and render them to clear true/false strings. If an expression fails to render or resolves to an empty value, Bosun falls back to evaluating the next available edge.

Each step can declare at most one success edge and one failure edge. Custom conditions are evaluated before the success fallback in the order they appear in the manifest.

Metadata in the Manifest

The root-level name and description fields now populate the workflow catalog inside the Bosun app. Use them to explain what your automation does—users see the text when browsing quick-start recipes and while configuring runs.

Input definitions and default values continue to live under inputs and values. Graph manifests can mix these with edges exactly as before.

Visual Graph Editor

When you configure a task run in the app, Bosun now shows a live graph preview. You can inspect the branches, rename steps, and verify start/end markers before launching. The editor keeps the manifest in sync, so edits made via the UI or in YAML stay aligned.

Tasks that were authored before graphs remain compatible; you can open them, see the inferred linear graph, and add branches over time.