Variables

Variables are fundamental to creating dynamic and interconnected Bosun workflows. They allow you to store and reference data throughout your tasks, enabling complex logic and data flow between different steps and agents.

Bosun provides several types of variables, with two common ones being:

• outputs: Used to access the results or output of a previous step.
• for_each.value: Used within a for_each loop to refer to the current item being processed.

Accessing Step Outputs (outputs)

Each step in a Bosun workflow can produce an output. In current manifests you should reference these outputs with outputs.<step_id>.

Example from Workflow:

steps:
  - id: fetch_sources
    name: Get source files
    run: find src -name "*.ts"

  - id: analyze_files
    name: Analyze files
    for_each:
      from: '{{ outputs.fetch_sources | split(pat="\n") | slice(end=5) | json_encode() }}'
      # ...

starts_with: fetch_sources
ends_with: analyze_files

edges:
  - from: fetch_sources
    to: analyze_files

In this snippet:

• The run: find src -name "*.ts" command stores a list of TypeScript file paths under outputs.fetch_sources.
• The for_each step then uses outputs.fetch_sources to retrieve this list. The templating expression {{ outputs.fetch_sources | split(pat="\n") | slice(end=5) | json_encode() }} processes this output to prepare it for the loop.

Referencing Outputs by Step ID

Every step needs an id, which is also how you keep templates readable:

  - id: fetch_sources
    name: Get source files
    run: find src -name "*.ts"

  - id: analyze_files
    name: Analyze files
    for_each:
      from: '{{ outputs.fetch_sources | split(pat="\n") | filter(value) | json_encode() }}'
      # ...

IDs must start with a letter or underscore and can contain alphanumeric characters, underscores, and hyphens. For templates, simple underscore-based IDs are usually the easiest to read.

Name steps early

Assign id values while drafting a manifest. Doing so keeps your templates readable and avoids brittle references.

Iterating with for_each.value

When you use a for_each loop, Bosun automatically makes the current item of the iteration available as for_each.value. This allows the agent or run command within the loop to operate on each item individually.

Example from Workflow:

steps:
  - id: fetch_sources
    run: find src -name "*.ts"

  - id: analyze_files
    name: Analyze files
    for_each:
      from: '{{ outputs.fetch_sources | split(pat="\n") | slice(end=5) | json_encode() }}'
      agent:
        extends: Coding
        instructions: "Refactor the code in file {{ for_each.value }} to improve readability."
        # ...

starts_with: fetch_sources
ends_with: analyze_files

edges:
  - from: fetch_sources
    to: analyze_files

Here:

• The for_each loop iterates over the list of file paths.
• For each iteration, {{ for_each.value }} holds the current file path (e.g., src/utils/helper.ts).
• This value is then injected into the instructions for the Coding agent, allowing it to specifically refactor that particular file.