What is Flow Stage?
Definition
Stages run in the order they're defined, and each one typically has a specific job: a preparation stage might run Policy Checks against a ChangeLog, a deployment stage might apply ChangeSets, and a verification stage might confirm the outcome and pull deployment history. Because each stage is distinct, a failure can be isolated to exactly where it happened rather than requiring a full investigation into the whole process. Stages can also define what happens when they fail; an endStage can trigger cleanup, send a notification, or simply halt the Flow cleanly, so a failure produces a clear, expected outcome instead of leaving a deployment in an ambiguous state.
Why breaking deployment into stages matters
A single, monolithic deployment script makes it hard to tell what actually happened when something goes wrong: did the checks pass and the deployment fail, or did the checks themselves catch something? Naming and separating each Stage removes that ambiguity. Anyone looking at a failed Flow can see immediately which stage failed and, from there, exactly what that stage was supposed to do. This granularity also makes partial re-runs possible: if only the deployment stage failed, there's usually no need to re-run the preparation stage that already passed.
How Flow Stages work
Each Stage contains one or more commands, run in the order they're listed, and stages themselves run in sequence within the Flow File. A common pattern uses three stages: preparation (validating a ChangeLog against Policy Checks), deployment (applying ChangeSets), and verification (confirming the result and pulling history). An endStage attached to a given stage defines what runs if that stage fails, whether that's a cleanup command, a report, or a notification, so failures are handled explicitly rather than left to whatever happens to run next by default. Stages can also be skipped conditionally based on arguments passed into the Flow, allowing one Flow File to serve slightly different needs across contexts.
How Liquibase helps
Liquibase Flows use Stages as their core building block, letting teams compose a deployment process out of small, named, independently reviewable pieces rather than one long script. Because each stage's success or failure is recorded individually, Structured Logging and Operation Reports can show exactly which stage a given deployment reached, which matters as much for a routine audit as it does for diagnosing a failure at the worst possible time. Naming conventions for stages also make it easier to compare Flow Files across projects, since a team can recognize the same pattern of preparation, deployment, and verification stages regardless of which specific commands each one runs.
