microsoft/openvmm
Publicmirrored fromhttps://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/dev_tools/flowey/pipelines.md
71lines · modecode
| 1 | # Pipelines |
| 2 | |
| 3 | Pipelines define complete automation workflows consisting of jobs that run nodes. See the [IntoPipeline trait documentation](https://openvmm.dev/rustdoc/linux/flowey_core/pipeline/trait.IntoPipeline.html) for detailed examples. |
| 4 | |
| 5 | ## Pipeline Jobs |
| 6 | |
| 7 | [`PipelineJob`](https://openvmm.dev/rustdoc/linux/flowey_core/pipeline/struct.PipelineJob.html) instances are configured using a builder pattern: |
| 8 | |
| 9 | ```rust,ignore |
| 10 | let job = pipeline |
| 11 | .new_job(platform, arch, "my-job") |
| 12 | .with_timeout_in_minutes(60) |
| 13 | .with_condition(some_param) |
| 14 | .ado_set_pool("my-pool") |
| 15 | .gh_set_pool(GhRunner::UbuntuLatest) |
| 16 | .dep_on(|ctx| { |
| 17 | // Define what nodes this job depends on |
| 18 | some_node::Request { /* ... */ } |
| 19 | }) |
| 20 | .finish(); |
| 21 | ``` |
| 22 | |
| 23 | ### Pipeline Parameters |
| 24 | |
| 25 | Parameters allow runtime configuration of pipelines. In Azure DevOps, parameters appear as editable fields in the Run pipeline UI (name, description, default). |
| 26 | |
| 27 |  |
| 28 | |
| 29 | ```rust,ignore |
| 30 | // Define a boolean parameter |
| 31 | let verbose = pipeline.new_parameter_bool( |
| 32 | "verbose", |
| 33 | "Run with verbose output", |
| 34 | ParameterKind::Stable, |
| 35 | Some(false) // default value |
| 36 | ); |
| 37 | |
| 38 | // Use the parameter in a job |
| 39 | let job = pipeline.new_job(...) |
| 40 | .dep_on(|ctx| { |
| 41 | let verbose = ctx.use_parameter(verbose); |
| 42 | // verbose is now a ReadVar<bool> |
| 43 | }) |
| 44 | .finish(); |
| 45 | ``` |
| 46 | |
| 47 | #### Stable vs Unstable Parameters |
| 48 | |
| 49 | Every parameter in flowey must be declared as either **Stable** or **Unstable** using [`ParameterKind`](https://openvmm.dev/rustdoc/linux/flowey_core/pipeline/enum.ParameterKind.html). This classification determines the parameter's visibility and API stability: |
| 50 | |
| 51 | **Stable Parameters ([`ParameterKind::Stable`](https://openvmm.dev/rustdoc/linux/flowey_core/pipeline/enum.ParameterKind.html#variant.Stable))** |
| 52 | |
| 53 | Stable parameters represent a **public, stable API** for the pipeline: |
| 54 | |
| 55 | - **External Visibility**: The parameter name is exposed as-is in the generated CI YAML, making it callable by external pipelines and users. |
| 56 | - **API Contract**: Once a parameter is marked stable, its name and behavior should be maintained for backward compatibility. Removing or renaming a stable parameter is a breaking change. |
| 57 | - **Use Cases**: |
| 58 | - Parameters that control major pipeline behavior (e.g., `enable_tests`, `build_configuration`) |
| 59 | - Parameters intended for use by other teams or external automation |
| 60 | - Parameters documented as part of the pipeline's public interface |
| 61 | |
| 62 | **Unstable Parameters ([`ParameterKind::Unstable`](https://openvmm.dev/rustdoc/linux/flowey_core/pipeline/enum.ParameterKind.html#variant.Unstable))** |
| 63 | |
| 64 | Unstable parameters are for **internal use** and experimentation: |
| 65 | |
| 66 | - **Internal Only**: The parameter name is prefixed with `__unstable_` in the generated YAML (e.g., `__unstable_debug_mode`), signaling that it's not part of the stable API. |
| 67 | - **No Stability Guarantee**: Unstable parameters can be renamed, removed, or have their behavior changed without notice. External consumers should not depend on them. |
| 68 | - **Use Cases**: |
| 69 | - Experimental features or debugging flags |
| 70 | - Internal pipeline configuration that may change frequently |
| 71 | - Parameters for development/testing that shouldn't be used in production |
| 72 | |