flowey_hvlite/pipelines/
build_docs.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! See [`BuildDocsCli`]
5
6use flowey::node::prelude::FlowPlatformLinuxDistro;
7use flowey::node::prelude::GhPermission;
8use flowey::node::prelude::GhPermissionValue;
9use flowey::node::prelude::ReadVar;
10use flowey::pipeline::prelude::*;
11use flowey_lib_common::git_checkout::RepoSource;
12use flowey_lib_hvlite::run_cargo_build::common::CommonTriple;
13
14#[derive(Copy, Clone, clap::ValueEnum)]
15enum PipelineConfig {
16    /// Run on all PRs targeting the OpenVMM `main` branch.
17    Pr,
18    /// Run on all commits that land in OpenVMM's `main` branch.
19    ///
20    /// The CI pipeline also publishes the guide to openvmm.dev.
21    Ci,
22}
23
24/// A pipeline defining documentation CI and PR jobs.
25#[derive(clap::Args)]
26pub struct BuildDocsCli {
27    #[clap(long)]
28    config: PipelineConfig,
29
30    #[clap(flatten)]
31    local_run_args: Option<crate::pipelines_shared::cfg_common_params::LocalRunArgs>,
32}
33
34impl IntoPipeline for BuildDocsCli {
35    fn into_pipeline(self, backend_hint: PipelineBackendHint) -> anyhow::Result<Pipeline> {
36        let Self {
37            config,
38            local_run_args,
39        } = self;
40
41        let mut pipeline = Pipeline::new();
42
43        // The docs pipeline should only run on the main branch.
44        {
45            let branches = vec!["main".into()];
46            match config {
47                PipelineConfig::Ci => {
48                    pipeline
49                        .gh_set_ci_triggers(GhCiTriggers {
50                            branches,
51                            ..Default::default()
52                        })
53                        .gh_set_name("OpenVMM Docs CI");
54                }
55                PipelineConfig::Pr => {
56                    pipeline
57                        .gh_set_pr_triggers(GhPrTriggers {
58                            branches,
59                            ..GhPrTriggers::new_draftable()
60                        })
61                        .gh_set_name("OpenVMM Docs PR");
62                }
63            }
64        }
65
66        let openvmm_repo_source = {
67            if matches!(backend_hint, PipelineBackendHint::Local) {
68                RepoSource::ExistingClone(ReadVar::from_static(crate::repo_root()))
69            } else if matches!(backend_hint, PipelineBackendHint::Github) {
70                RepoSource::GithubSelf
71            } else {
72                anyhow::bail!(
73                    "Unsupported backend: Docs Pipeline only supports Local and GitHub backends"
74                );
75            }
76        };
77
78        if let RepoSource::GithubSelf = &openvmm_repo_source {
79            pipeline.gh_set_flowey_bootstrap_template(
80                crate::pipelines_shared::gh_flowey_bootstrap_template::get_template(),
81            );
82        }
83
84        let cfg_common_params = crate::pipelines_shared::cfg_common_params::get_cfg_common_params(
85            &mut pipeline,
86            backend_hint,
87            local_run_args,
88        )?;
89
90        pipeline.inject_all_jobs_with(move |job| {
91            job.dep_on(&cfg_common_params)
92                .dep_on(|_| flowey_lib_hvlite::_jobs::cfg_versions::Request {})
93                .dep_on(
94                    |_| flowey_lib_hvlite::_jobs::cfg_hvlite_reposource::Params {
95                        hvlite_repo_source: openvmm_repo_source.clone(),
96                    },
97                )
98                .gh_grant_permissions::<flowey_lib_common::git_checkout::Node>([(
99                    GhPermission::Contents,
100                    GhPermissionValue::Read,
101                )])
102                .gh_grant_permissions::<flowey_lib_common::gh_task_azure_login::Node>([(
103                    GhPermission::IdToken,
104                    GhPermissionValue::Write,
105                )])
106        });
107
108        // We need to maintain a list of all jobs, so we can hang the "all good"
109        // job off of them. This is requires because github status checks only allow
110        // specifying jobs, and not workflows.
111        // There's more info in the following discussion:
112        // <https://github.com/orgs/community/discussions/12395>
113        let mut all_jobs = Vec::new();
114
115        // emit mdbook guide build job
116        let (pub_guide, use_guide) = pipeline.new_typed_artifact("guide");
117        let job = pipeline
118            .new_job(
119                FlowPlatform::Linux(FlowPlatformLinuxDistro::Ubuntu),
120                FlowArch::X86_64,
121                "build mdbook guide",
122            )
123            .gh_set_pool(crate::pipelines_shared::gh_pools::gh_hosted_x64_linux())
124            .dep_on(|ctx| flowey_lib_hvlite::build_guide::Request {
125                built_guide: ctx.publish_typed_artifact(pub_guide),
126            })
127            .finish();
128
129        all_jobs.push(job);
130
131        // emit rustdoc jobs
132        let (pub_rustdoc_linux, use_rustdoc_linux) =
133            pipeline.new_typed_artifact("x64-linux-rustdoc");
134        let (pub_rustdoc_win, use_rustdoc_win) = pipeline.new_typed_artifact("x64-windows-rustdoc");
135        for (target, platform, pool, pub_rustdoc) in [
136            (
137                CommonTriple::X86_64_WINDOWS_MSVC,
138                FlowPlatform::Windows,
139                crate::pipelines_shared::gh_pools::gh_hosted_x64_windows(),
140                pub_rustdoc_win,
141            ),
142            (
143                CommonTriple::X86_64_LINUX_GNU,
144                FlowPlatform::Linux(FlowPlatformLinuxDistro::Ubuntu),
145                crate::pipelines_shared::gh_pools::gh_hosted_x64_linux(),
146                pub_rustdoc_linux,
147            ),
148        ] {
149            let job = pipeline
150                .new_job(
151                    platform,
152                    FlowArch::X86_64,
153                    format!("build and check docs [x64-{platform}]"),
154                )
155                .gh_set_pool(pool)
156                .dep_on(|ctx| flowey_lib_hvlite::build_rustdoc::Request {
157                    target_triple: target.as_triple(),
158                    docs: ctx.publish_typed_artifact(pub_rustdoc),
159                })
160                .finish();
161
162            all_jobs.push(job);
163        }
164
165        // emit consolidated gh pages publish job
166        if matches!(config, PipelineConfig::Ci) {
167            let pub_artifact = if matches!(backend_hint, PipelineBackendHint::Local) {
168                let (publish, _use) = pipeline.new_typed_artifact("gh-pages");
169                Some(publish)
170            } else {
171                None
172            };
173
174            let job = pipeline
175                .new_job(FlowPlatform::Linux(FlowPlatformLinuxDistro::Ubuntu), FlowArch::X86_64, "publish openvmm.dev")
176                .gh_set_pool(crate::pipelines_shared::gh_pools::gh_hosted_x64_linux())
177                .dep_on(
178                    |ctx| flowey_lib_hvlite::_jobs::consolidate_and_publish_gh_pages::Params {
179                        rustdoc_linux: ctx.use_typed_artifact(&use_rustdoc_linux),
180                        rustdoc_windows: ctx.use_typed_artifact(&use_rustdoc_win),
181                        guide: ctx.use_typed_artifact(&use_guide),
182                        output: if let Some(pub_artifact) = pub_artifact {
183                            ctx.publish_typed_artifact(pub_artifact)
184                        } else {
185                            ctx.new_done_handle().discard_result()
186                        }
187                    },
188                )
189                .gh_grant_permissions::<flowey_lib_hvlite::_jobs::consolidate_and_publish_gh_pages::Node>([
190                    (GhPermission::IdToken, GhPermissionValue::Write),
191                    (GhPermission::Pages, GhPermissionValue::Write),
192                ])
193                .finish();
194
195            all_jobs.push(job);
196        }
197
198        if matches!(config, PipelineConfig::Pr) {
199            // Add a job that depends on all others as a workaround for
200            // https://github.com/orgs/community/discussions/12395.
201            //
202            // This workaround then itself requires _another_ workaround, requiring
203            // the use of `gh_dangerous_override_if`, and some additional custom job
204            // logic, to deal with https://github.com/actions/runner/issues/2566.
205            //
206            // TODO: Add a way for this job to skip flowey setup and become a true
207            // no-op.
208            let all_good_job = pipeline
209                .new_job(
210                    FlowPlatform::Linux(FlowPlatformLinuxDistro::Ubuntu),
211                    FlowArch::X86_64,
212                    "openvmm build docs gates",
213                )
214                .gh_set_pool(crate::pipelines_shared::gh_pools::gh_hosted_x64_linux())
215                // always run this job, regardless whether or not any previous jobs failed
216                .gh_dangerous_override_if("always() && github.event.pull_request.draft == false")
217                .gh_dangerous_global_env_var("ANY_JOBS_FAILED", "${{ contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'failure') }}")
218                .dep_on(|ctx| flowey_lib_hvlite::_jobs::all_good_job::Params {
219                    did_fail_env_var: "ANY_JOBS_FAILED".into(),
220                    done: ctx.new_done_handle(),
221                })
222                .finish();
223
224            for job in all_jobs.iter() {
225                pipeline.non_artifact_dep(&all_good_job, job);
226            }
227        }
228
229        Ok(pipeline)
230    }
231}
flowey_hvlite/pipelines/build_docs.rs

flowey_hvlite/pipelines/
build_docs.rs
