Reuse the release artifact during deployment (#8181)

* fix: deploy the prepared release artifact

* style: format prepared artifact selection

* test: restore release artifact preflight fixture

Author: chubes4

src/commands/deploy.rs

@@ -370,6 +370,7 @@ fn build_config(args: &DeployArgs, skip_build: bool) -> DeployConfig {
         head: args.head,
         requested_ref: args.requested_ref.clone(),
         tagged: args.tagged,
+        prepared_artifact: None,
     }
 }
 

src/core/deploy/execution/mod.rs

@@ -55,12 +55,13 @@ mod tests {
         artifact_requires_component_extract_command, resolve_preflight_artifact_path,
         validate_predeploy_artifact_version,
     };
-    use super::prepare::failed_component_deploy_result;
+    use super::prepare::{failed_component_deploy_result, prepare_component_deploy};
     use super::release_plan::{release_artifact_plan, should_try_download_release_artifact};
     use super::strategies::cleanup_deploy_build_artifact;
     use super::{bound_captured_read, ReleaseArtifactPlan, ARTIFACT_VERSION_READ_LIMIT_BYTES};
-    use crate::core::component::{ArtifactInput, Component, VersionTarget};
-    use crate::core::deploy::types::DeployConfig;
+    use crate::core::component::{ArtifactInput, Component, ComponentScriptsConfig, VersionTarget};
+    use crate::core::deploy::types::{DeployConfig, PreparedDeployArtifact};
+    use crate::core::project::Project;
     use std::io::Write;
     use std::process::Command;
 
@@ -116,6 +117,70 @@ mod tests {
         assert_eq!(result.error.as_deref(), Some("deploy failed"));
     }
 
+    #[test]
+    fn prepared_artifact_skips_local_build_invocation() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let durable_artifact = temp.path().join("release.tar.gz");
+        let build_counter = temp.path().join("build-count");
+        std::fs::write(&durable_artifact, "release payload").expect("artifact");
+        let mut component = Component {
+            id: "fixture".to_string(),
+            local_path: temp.path().display().to_string(),
+            remote_path: "plugins/fixture".to_string(),
+            build_artifact: Some("build/fixture.tar.gz".to_string()),
+            extract_command: Some("tar -xzf {{artifact}}".to_string()),
+            ..Component::default()
+        };
+        component.scripts = Some(ComponentScriptsConfig {
+            build: vec![format!("printf build >> {}", build_counter.display())],
+            ..ComponentScriptsConfig::default()
+        });
+        let config = DeployConfig {
+            component_ids: vec![component.id.clone()],
+            all: false,
+            outdated: false,
+            behind_upstream: false,
+            dry_run: false,
+            check: false,
+            force: true,
+            skip_build: true,
+            keep_deps: false,
+            skip_deps_hydration: false,
+            expected_version: Some("1.2.3".to_string()),
+            no_pull: true,
+            head: false,
+            requested_ref: None,
+            tagged: false,
+            prepared_artifact: Some(PreparedDeployArtifact {
+                component_id: component.id.clone(),
+                path: "build/fixture.tar.gz".to_string(),
+                durable_path: durable_artifact.display().to_string(),
+                size_bytes: 15,
+                sha256: crate::core::deploy::sha256_file(&durable_artifact).expect("sha"),
+                version: "1.2.3".to_string(),
+                tag: "v1.2.3".to_string(),
+                source_commit: "0123456789abcdef".to_string(),
+            }),
+        };
+
+        let prepared = prepare_component_deploy(
+            &component,
+            &config,
+            "/srv/site",
+            &Project::default(),
+            Some("1.2.3".to_string()),
+            None,
+            None,
+        )
+        .expect("prepared artifact should pass local preflight");
+
+        assert_eq!(prepared.artifact_path, Some(durable_artifact));
+        assert!(
+            !build_counter.exists(),
+            "prepared deployment must not build"
+        );
+    }
+
     #[test]
     fn archive_artifact_without_component_extract_is_allowed_by_deploy_override() {
         assert!(!artifact_requires_component_extract_command(
@@ -165,6 +230,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         let result = resolve_preflight_artifact_path(
@@ -225,6 +291,7 @@ mod tests {
             head: true,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         assert!(!should_try_download_release_artifact(
@@ -258,6 +325,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: true,
+            prepared_artifact: None,
         };
 
         assert!(!should_try_download_release_artifact(
@@ -302,6 +370,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         assert!(should_try_download_release_artifact(
@@ -346,6 +415,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         assert!(should_try_download_release_artifact(
@@ -381,6 +451,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         match release_artifact_plan(&component, &config, false, false) {
@@ -429,6 +500,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         assert!(should_try_download_release_artifact(
@@ -502,6 +574,7 @@ mod tests {
             head: true,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         };
 
         let artifact = resolve_preflight_artifact_path(

src/core/deploy/execution/prepare.rs

@@ -44,31 +44,63 @@ pub(crate) fn prepare_component_deploy(
     let is_git_deploy = component.deploy_strategy.as_deref() == Some("git");
     let is_file_deploy = component.deploy_strategy.as_deref() == Some("file");
 
+    if let Some(prepared_artifact) = config.prepared_artifact.as_ref() {
+        if is_git_deploy || is_file_deploy {
+            return Err(failed_component_deploy_result(
+                component,
+                base_path,
+                local_version,
+                remote_version,
+                None,
+                "Prepared artifacts require an artifact deploy strategy".to_string(),
+            ));
+        }
+        if let Err(error) =
+            prepared_artifact.validate(&component.id, config.expected_version.as_deref())
+        {
+            return Err(failed_component_deploy_result(
+                component,
+                base_path,
+                local_version,
+                remote_version,
+                None,
+                error.to_string(),
+            ));
+        }
+    }
+
     // Try downloading release artifact from GitHub instead of building locally.
     // This is the preferred path when the component has remote_url set.
-    let release_artifact: Option<PathBuf> =
+    let release_artifact: Option<PathBuf> = if let Some(prepared_artifact) =
+        config.prepared_artifact.as_ref()
+    {
+        Some(PathBuf::from(prepared_artifact.effective_path()))
+    } else {
         match release_artifact_plan(component, config, is_git_deploy, is_file_deploy) {
-            ReleaseArtifactPlan::Reuse { tag, .. } => match release_artifact {
-                Some(artifact) => Some(artifact.path),
-                None => return Err(failed_component_deploy_result(
-                    component, base_path, local_version, remote_version, None,
-                    format!("artifact source release_asset failed for '{}' tag {tag}: verified run-scoped artifact is unavailable. Refusing to fall back to local_build", component.id),
-                ).with_artifact_source(DeployArtifactSource::ReleaseAsset)),
-            },
-            ReleaseArtifactPlan::LocalBuild { reason } => {
-                if config.dry_run {
-                    log_status!(
-                        "deploy",
-                        "Local rebuild planned for '{}': {}",
-                        component.id,
-                        reason
-                    );
+                ReleaseArtifactPlan::Reuse { tag, .. } => match release_artifact {
+                    Some(artifact) => Some(artifact.path),
+                    None => return Err(failed_component_deploy_result(
+                        component, base_path, local_version, remote_version, None,
+                        format!("artifact source release_asset failed for '{}' tag {tag}: verified run-scoped artifact is unavailable. Refusing to fall back to local_build", component.id),
+                    ).with_artifact_source(DeployArtifactSource::ReleaseAsset)),
+                },
+                ReleaseArtifactPlan::LocalBuild { reason } => {
+                    if config.dry_run {
+                        log_status!(
+                            "deploy",
+                            "Local rebuild planned for '{}': {}",
+                            component.id,
+                            reason
+                        );
+                    }
+                    None
                 }
-                None
             }
-        };
+    };
     let artifact_source = if is_git_deploy || is_file_deploy {
         None
+    } else if config.prepared_artifact.is_some() {
+        Some(DeployArtifactSource::Prepared)
     } else if release_artifact.is_some() {
         Some(DeployArtifactSource::ReleaseAsset)
     } else {
@@ -184,7 +216,10 @@ pub(crate) fn prepare_component_deploy(
     generated_cleanup_guard.disarm();
 
     let cleanup_local_artifact = artifact_path.as_ref().is_some_and(|_| {
-        release_artifact.is_none() && !config.skip_build && !is_self_deploy(component)
+        config.prepared_artifact.is_none()
+            && release_artifact.is_none()
+            && !config.skip_build
+            && !is_self_deploy(component)
     });
 
     // Capture provenance now, while the source tree is at the built state and the
@@ -195,6 +230,8 @@ pub(crate) fn prepare_component_deploy(
         BuildSource::GitPush
     } else if is_file_deploy {
         BuildSource::FileCopy
+    } else if config.prepared_artifact.is_some() {
+        BuildSource::PreparedArtifact
     } else if release_artifact.is_some() {
         BuildSource::DownloadedRelease
     } else if config.skip_build {

src/core/deploy/mod.rs

@@ -21,10 +21,12 @@ pub use planning::{
     bucket_release_states, calculate_release_state, calculate_release_state_from_baseline,
     classify_release_state,
 };
+pub(crate) use types::sha256_file;
 pub use types::{
     compare_deployed_versions, parse_bulk_component_ids, ComponentDeployResult, ComponentStatus,
     DeployConfig, DeployOrchestrationResult, DeployReason, DeploySummary, MultiDeployResult,
-    MultiDeploySummary, ProjectDeployResult, ReleaseState, ReleaseStateBuckets, ReleaseStateStatus,
+    MultiDeploySummary, PreparedDeployArtifact, ProjectDeployResult, ReleaseState,
+    ReleaseStateBuckets, ReleaseStateStatus,
 };
 pub use version_overrides::fetch_remote_versions;
 pub use version_overrides::{RemoteVersionProbeFailure, RemoteVersionProbeResult};
@@ -78,9 +80,8 @@ pub fn fetch_project_remote_versions(
 
 /// Deploy components across multiple projects.
 ///
-/// Builds each project independently. Keeping build artifacts local to each
-/// project run avoids lifecycle coupling between deploy target cleanup and
-/// later projects in the same command.
+/// Builds each project independently unless an upstream workflow supplies a
+/// prepared artifact, which is validated once and reused unchanged for every target.
 ///
 /// Unknown project IDs are skipped (not fatal) — fleet configs can
 /// accumulate stale references that shouldn't block the rest.
@@ -134,6 +135,12 @@ pub fn run_multi(
         ));
     }
 
+    if let Some(prepared_artifact) = config.prepared_artifact.as_ref() {
+        for component_id in component_ids {
+            prepared_artifact.validate(component_id, config.expected_version.as_deref())?;
+        }
+    }
+
     log_status!(
         "deploy",
         "Deploying {:?} to {} project(s){}...",
@@ -189,6 +196,7 @@ pub fn run_multi(
             head: config.head,
             requested_ref: config.requested_ref.clone(),
             tagged: config.tagged,
+            prepared_artifact: config.prepared_artifact.clone(),
         };
 
         match run_with_release_artifacts(project_id, &project_config, &mut release_artifacts) {
@@ -306,6 +314,7 @@ mod tests {
     use super::*;
     use crate::core::project::{Project, ProjectComponentAttachment};
     use crate::test_support::with_isolated_home;
+    use std::path::Path;
 
     fn deploy_config() -> DeployConfig {
         DeployConfig {
@@ -326,6 +335,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         }
     }
 
@@ -356,4 +366,37 @@ mod tests {
             }));
         });
     }
+
+    #[test]
+    fn prepared_artifact_mismatch_fails_before_project_ssh_resolution() {
+        with_isolated_home(|_| {
+            project::save(&Project {
+                id: "site".to_string(),
+                ..Project::default()
+            })
+            .expect("save project");
+            let missing_path = Path::new("/definitely/missing/prepared-artifact.zip");
+            let config = DeployConfig {
+                prepared_artifact: Some(PreparedDeployArtifact {
+                    component_id: "plugin".to_string(),
+                    path: missing_path.display().to_string(),
+                    durable_path: missing_path.display().to_string(),
+                    size_bytes: 0,
+                    sha256: "not-a-real-sha".to_string(),
+                    version: "1.2.3".to_string(),
+                    tag: "v1.2.3".to_string(),
+                    source_commit: "0123456789abcdef".to_string(),
+                }),
+                ..deploy_config()
+            };
+
+            let error = run_multi(&["site".to_string()], &["plugin".to_string()], &config)
+                .expect_err("missing prepared artifact must stop before any target mutation");
+
+            assert!(
+                error.details.to_string().contains("prepared-artifact.zip"),
+                "prepared artifact validation must fail before SSH resolution: {error:?}"
+            );
+        });
+    }
 }

src/core/deploy/orchestration/mod.rs

@@ -325,6 +325,8 @@ pub(super) fn deploy_components(
                 &["rev-parse", "--abbrev-ref", "HEAD"],
             )
             .map(|branch| format!("{} (HEAD)", branch))
+        } else if let Some(prepared_artifact) = config.prepared_artifact.as_ref() {
+            Some(prepared_artifact.tag.clone())
         } else {
             None
         };
@@ -340,6 +342,9 @@ pub(super) fn deploy_components(
                 &identity.resolution_mode,
             );
         }
+        if let Some(prepared_artifact) = config.prepared_artifact.clone() {
+            result = result.with_prepared_artifact(prepared_artifact);
+        }
 
         // Attach explicit build provenance to every result, regardless of strategy.
         let mut build_provenance = prepared.build_provenance.clone();
@@ -348,6 +353,8 @@ pub(super) fn deploy_components(
             build_provenance.built_from_commit = Some(identity.resolved_sha.clone());
         } else if let Some(artifact) = resolved_release_artifacts.get(&component.id) {
             build_provenance.built_from_commit = artifact.commit.clone();
+        } else if let Some(prepared_artifact) = config.prepared_artifact.as_ref() {
+            build_provenance.built_from_commit = Some(prepared_artifact.source_commit.clone());
         }
         result = result.with_build_provenance(build_provenance);
 
@@ -529,6 +536,7 @@ mod tests {
             head: false,
             requested_ref: None,
             tagged: false,
+            prepared_artifact: None,
         }
     }