Skip to main content

Task Graphs and Branching

Bosun tasks are defined as graphs. Every workflow declares its steps, the first node to start from, the terminal node to end on, and the transitions between them. This lets you branch, merge, and conditionally skip work without writing imperative control flow.

Graph Manifest Structure​

Every workflow manifest includes three graph 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 non-terminal node should have the transitions Bosun needs to continue the run. Each edge optionally declares an on condition.

Every step needs a stable id. Bosun uses these IDs in edges, templates, and run output references.

Name steps before wiring edges

Assign the id field as soon as you draft the step so your edges and templates stay readable.

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

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 an earlier 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.

Branching on structured failures​

Failure edges become much more powerful when you pair them with Custom Schemas. Agents can return rich JSON through stop_schema/fail_schema, Bosun stores that data under errors.<step>[i].reason, and your graph edges decide where to go next based on those fields.

A Bosun regression-manifest fixture shows a simple version of this pattern: an agent required to call task_failed with { summary, blockers, blocking } fans out to a recovery step via an on: failure edge. You can take the same idea further by looking inside the payload.

Example: fan out work when an agent fails​

steps:
  - id: regression_auditor
    name: Audit upgraded services
    agent:
      extends: Coding
      instructions: |
        Run the regression suite. If anything fails, stop immediately and call `task_failed` with the services that need manual intervention.
      fail_schema:
        type: object
        required: [summary, retryable, owners]
        properties:
          summary:
            type: string
          retryable:
            type: boolean
          owners:
            type: array
            items:
              type: object
              required: [service, assignee]
              properties:
                service:
                  type: string
                assignee:
                  type: string

  - id: notify_success
    run: echo "All services passed" > status.txt

  - id: dispatch_fixers
    for_each:
      from: '{{ errors.regression_auditor[0].reason.owners | json_encode() }}'
      parallel: true
      agent:
        extends: Coding
        instructions: |
          Address the regression in {{ for_each.value.service }} and hand it back to {{ for_each.value.assignee }}.

  - id: summarize
    agent:
      extends: pull_request
      instructions: "Open or update the PR once all owners report back."

starts_with: regression_auditor
ends_with: summarize

edges:
  - from: regression_auditor
    to: notify_success
    on: success
  - from: regression_auditor
    to: dispatch_fixers
    on: failure
  - from: dispatch_fixers
    to: summarize

How it works:

  1. regression_auditor either succeeds and flows to notify_success, or fails with a structured payload.
  2. The failure edge routes control to dispatch_fixers, which turns the list of owners from errors.regression_auditor[0].reason into a parallel for_each run. Each iteration inherits the service/assignee details from the failure payload.
  3. When the fan-out loop finishes, the graph continues to summarize, where you can aggregate the fixes or open a PR.

Because the schema is enforced at runtime, you can rely on fields such as retryable or owners existing before you branch. If you only need to check a flag, add a conditional expression to the edge instead:

edges:
  - from: regression_auditor
    to: dispatch_fixers
    on: '{{ errors.regression_auditor[0].reason.retryable == true }}'
  - from: regression_auditor
    to: escalate
    on: failure