microsoft/openvmm
Publicmirrored fromhttps://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/dev_tools/flowey.md
56lines · modecode
| 1 | # Flowey |
| 2 | |
| 3 | Flowey is an in-house, Rust library for writing maintainable, cross-platform automation. It enables developers to define CI/CD pipelines and local workflows as type-safe Rust code that can generate backend-specific YAML (Azure DevOps, GitHub Actions) or execute directly on a local machine. Rather than writing automation logic in YAML with implicit dependencies, flowey treats automation as first-class Rust code with explicit, typed dependencies tracked through a directed acyclic graph (DAG). |
| 4 | |
| 5 | ## Why Flowey? |
| 6 | |
| 7 | Traditional CI/CD pipelines using YAML-based configuration (e.g., Azure DevOps Pipelines, GitHub Actions workflows) have several fundamental limitations that become increasingly problematic as projects grow in complexity: |
| 8 | |
| 9 | ### The Problems with Traditional YAML Pipelines |
| 10 | |
| 11 | #### Non-Local Reasoning and Global State |
| 12 | |
| 13 | - YAML pipelines heavily rely on global state and implicit dependencies (environment variables, file system state, installed tools) |
| 14 | - Understanding what a step does often requires mentally tracking state mutations across the entire pipeline |
| 15 | - Debugging requires reasoning about the entire pipeline context rather than isolated units of work |
| 16 | - Changes in one part of the pipeline can have unexpected effects in distant, seemingly unrelated parts |
| 17 | |
| 18 | #### Maintainability Challenges |
| 19 | |
| 20 | - YAML lacks type safety, making it easy to introduce subtle bugs (typos in variable names, incorrect data types, etc.) |
| 21 | - No compile-time validation means errors only surface at runtime |
| 22 | - Refactoring is risky and error-prone without automated tools to catch breaking changes |
| 23 | - Code duplication is common because YAML lacks good abstraction mechanisms |
| 24 | - Testing pipeline logic requires actually running the pipeline, making iteration slow and expensive |
| 25 | |
| 26 | #### Platform Lock-In |
| 27 | |
| 28 | - Pipelines are tightly coupled to their specific CI backend (ADO, GitHub Actions, etc.) |
| 29 | - Multi-platform support means maintaining multiple, divergent YAML files |
| 30 | |
| 31 | #### Local Development Gaps |
| 32 | |
| 33 | - Developers can't easily test pipeline changes before pushing to CI |
| 34 | - Reproducing CI failures locally is difficult or impossible |
| 35 | - The feedback loop is slow: push → wait for CI → debug → repeat |
| 36 | |
| 37 | ### Flowey's Solution |
| 38 | |
| 39 | Flowey addresses these issues by treating automation as **first-class Rust code**: |
| 40 | |
| 41 | - **Type Safety**: Rust's type system catches errors at compile-time rather than runtime |
| 42 | - **Local Reasoning**: Dependencies are explicit through typed variables, not implicit through global state |
| 43 | - **Portability**: Write once, generate YAML for any backend (ADO, GitHub Actions, or run locally) |
| 44 | - **Reusability**: Nodes are composable building blocks that can be shared across pipelines |
| 45 | |
| 46 | ## Flowey's Directory Structure |
| 47 | |
| 48 | Flowey is architected as a standalone tool with a layered crate structure that separates project-agnostic core functionality from project-specific implementations: |
| 49 | |
| 50 | - **`flowey_core`**: Provides the core types and traits shared between user-facing and internal Flowey code, such as the essential abstractions for nodes and pipelines. |
| 51 | - **`flowey`**: Thin wrapper around `flowey_core` that exposes the public API for defining nodes and pipelines. |
| 52 | - **`flowey_cli`**: Command-line interface for running flowey - handles YAML generation, local execution, and pipeline orchestration. |
| 53 | - **`schema_ado_yaml`**: Rust types for Azure DevOps YAML schemas used during pipeline generation. |
| 54 | - **`flowey_lib_common`**: Ecosystem-wide reusable nodes (installing Rust, running Cargo, downloading tools, etc.) that could be useful across projects outside of OpenVMM. |
| 55 | - **`flowey_lib_hvlite`**: OpenVMM-specific nodes and workflows that build on the common library primitives. |
| 56 | - **`flowey_hvlite`**: The OpenVMM pipeline definitions that compose nodes from the libraries above into complete CI/CD workflows. |
| 57 | |