Skip to content

Workflows

Verification

Why a successful action is not a verified outcome, and how to write assertions.

A step reports what it did. Verification independently reads back what is true. Keeping these separate catches a class of failure that exit codes do not.

Writing a useful assertion

Assert against the original symptom, measured the way the symptom was measured. If the request said a volume was full, assert on a fresh usage measurement. If it said a service was unreachable, assert on a request from outside the host. If it said a machine should exist with a given shape, read the shape back from the platform rather than from the build step's own output.

Three outcomes, not two

  • Verified — the action ran and the assertion passed. The run closes with evidence.
  • Failed — the action did not complete. Retry policy applies; nothing is reported as done.
  • Unverified — the action completed but the assertion did not pass. The run escalates. This is never reported as success.

Watch the unverified rate

A rising rate of unverified outcomes is the earliest signal that a workflow is drifting away from the reality it was written against. Alert on it.

Scope of this documentation

This page describes how the StackHeal platform is designed to behave. This website does not execute workflows or connect to infrastructure — see the repository README for the backend integration points.