Skip to main content

Incremental workflow builds

Incremental workflow builds snapshot your repository and runtime context after every step. Each snapshot contains the committed diff, step outputs, errors, and manifest metadata so Bosun can reconstruct the workspace, resume unfinished runs, or simply provide a time-ordered audit trail.

Snapshots are captured automatically whenever a step succeeds or fails. The coding agent already commits after every change, so you do not need to modify existing manifests to benefit from incremental builds.

What a snapshot stores​

Every snapshot records a durable view of the run at that point:

  • Git patch chain: committed changes between the previous snapshot and the latest commit.
  • Runtime context: task inputs, step outputs, errors, and for_each aggregate data required to restart subsequent steps without recomputing work.
  • Manifest signatures: hashes derived from the step definition and graph edges. These signatures guarantee that Bosun only resumes when earlier steps are unchanged.
  • Metadata: base ref, source and target commits, and branch names used to replay the step chain on resume.
  • Outcome: success or failure, plus a resumable flag when the snapshot reached the storage layer.

Bosun ignores uncommitted files when building the patch chain, so make sure each step commits the state you expect to revisit (coding agents do this automatically). Built-in agents do this for you; custom run steps should call git commit once they reach a stable checkpoint.

Inspecting snapshots in the app​

Open any run and locate the Step snapshots panel:

  1. Each row maps to a manifest step with a color-coded outcome, timestamp, diff shortstat, and an inline preview of the patch.
  2. Selecting a snapshot highlights the matching entry inside the diff overlay, so you can cycle between live updates and stored snapshots without leaving the run page.
  3. The panel also exposes the resumable state. Skipped snapshots (for example, when a step never committed) stay visible but cannot be used to resume.

Use the patch preview to spot unintended changes or to answer “what did the agent do in this step?” without opening the pull request. The runtime context stored alongside each snapshot is also exposed in the resume dialog so you can inspect inputs, outputs, and errors before restarting the run.

Resuming from a snapshot​

Resuming spins up a brand-new session, reapplies the recorded patch chain, rehydrates the runtime context (including step outputs), and jumps directly to the next step after your chosen snapshot.

In the UI

  1. Click Resume beside any resumable snapshot.
  2. Optionally pick a task version. Bosun compares manifest signatures for every step up to the snapshot, so earlier instructions must remain identical.
  3. Review the compatibility check. If anything changed—branching conditions, step bodies, or graph paths—the dialog surfaces the precise reason (for example, “Earlier steps changed in this version”).
  4. Confirm to start a new run. The new session’s metadata links back to the original, making the lineage easy to audit.

Designing manifests for incremental builds​

Incremental builds work best when steps describe a single, reviewable change. A common pattern is: analyze → write changes → save guidance → run verification.

steps:
  - id: discover_delta
    run: pnpm lint --filter '{{ inputs.package }}'

  - id: draft_migration
    agent:
      extends: Coding
      instructions: >-
        Apply the migration plan to {{ inputs.package }} and commit the files.
      constraints:
        - Keep unrelated modules untouched.

  - id: capture_notes
    save_artifact:
      name: "Migration notes for {{ inputs.package }}"
      content: |
        {{ outputs.draft_migration.summary }}

  - id: verify
    run: pnpm test --filter '{{ inputs.package }}'

starts_with: discover_delta
ends_with: verify

edges:
  - from: discover_delta
    to: draft_migration
  - from: draft_migration
    to: capture_notes
  - from: capture_notes
    to: verify

Recommendations:

  • Commit per step so snapshots capture a minimal patch. Long-lived steps should create intermediate commits even if they eventually squash in the pull request.
  • Write migration guides as artifacts (see Migrating legacy code) so resumed runs inherit the same instructions without recomputing expensive discovery work.
  • Use for_each for slices when rolling the same change through multiple files or services. Snapshot metadata includes aggregated for_each outputs, and resuming restarts the entire for_each step with the original input list.
  • Keep continue_on_error: true on collection steps so one failure still yields a usable snapshot. You can resume from the failed step, fix instructions, and continue without losing earlier successes.

Lock verification commands to the run by setting runtime overrides. That way every resume replays the same checks automatically:

{
  "config_overrides": {
    "commands": [
      {
        "name": "targeted-tests",
        "command": "pnpm test --filter '{{ inputs.package }}'"
      },
      {
        "name": "lint",
        "command": "pnpm lint --filter '{{ inputs.package }}'"
      }
    ]
  }
}

Operational notes​

  • Snapshots capture the primary repository only. Secondary repositories remain read-only context and are not included in the patch chain.
  • The snapshot status must be stored to resume. When a step never created a commit, Bosun still records the context but disables the resume action.